Refactor a Claude Code project's project-level context (CLAUDE.md + optional MEMORY/) into "AGENTS.md as the single
source of truth (SSOT), with CLAUDE.md reduced to a thin shell containing only Claude-specific content"—one source of truth, with Claude Code and agents that read
AGENTS.md (such as Qoder) each loading it through their own entry point, with no need to maintain two copies.
Why design it this way
The core is to make AGENTS.md the single source of truth: all project context is maintained in only one place here, andCLAUDE.md degrades into a
thin shell that imports it (plus a small number of Claude-specific escape hatches). This way Claude Code (via CLAUDE.md → @AGENTS.md) and any agent that reads
AGENTS.md share the same content, and a change in one place takes effect immediately.AGENTS.md is the cross-agent de facto standard—
any agent that reads it (Qoder / Codex, etc.)natively recognizesit, with no extra configuration needed (for an example, see Qoder's official Rules documentation
original text: "copy your AGENTS.md file to your project directory.
The Agent will automatically recognize and utilize the rules defined in the file"). So de-branding
AGENTS.md alone makes the project usable by these agents in a single step.@MEMORY/MEMORY.md is written inside
AGENTS.md (R2), and on the Claude Code side, the memory index is definitely loaded via recursive @ expansion.
When to use / not use
Use
- The user says "migrate CLAUDE.md to AGENTS.md / make the project usable in Qoder too / have both tools coexist / migrate agent context"
- The user is switching from Claude Code to an agent that reads AGENTS.md (such as Qoder / Codex), or wants two IDEs to use the same project at the same time
- The project root has
CLAUDE.md(with or withoutMEMORY/), and you want to generate a cross-agent universalAGENTS.md
Do not use
- Migrate permissions(
.claude/settings.local.json) or MCP configuration—this skill does not touch them; both are tool-specific and sensitive - Modify
scripts//references//eval/—only touch context files (CLAUDE.md / AGENTS.md / MEMORY) - Delete
CLAUDE.md—this skill preserves thin-shell coexistence; if the user wants to use only an agent that reads AGENTS.md and completely delete CLAUDE.md, explicit confirmation is required - Migrate to an agent that does not read
AGENTS.mdagent—this skill's main path (generating a universalAGENTS.md) holds for any agent that readsAGENTS.md(Qoder / Codex, etc.); it is inapplicable only when the target agent does not readAGENTS.mdat all (and recognizes only its own proprietary context format) - Generate agent-specific trigger-based rule files(such as Qoder's
.qoder/rules/)—such mechanisms are mostly undocumented officially, so leave it to the user to configure them in the target agent IDE; this skill only producesAGENTS.md+ thin-shellCLAUDE.md+MEMORY/ - Build project context from scratch(no existing CLAUDE.md)—there is no source to migrate, so just write
AGENTS.mddirectly; the rewrite process is not needed
Input / Output
Input
| Input | Required | Description |
|---|---|---|
| Project root directory | Yes | Default cwd; must contain CLAUDE.md |
MEMORY/ |
No | If present, de-brand it as well (Step 3); if absent, skip |
| Original CLAUDE.md snapshot | Automatic | Step 1 automatically snapshots to .migration-backup/CLAUDE.md.original, for Step 5 coverage comparison |
Output
<project-root>/
├── AGENTS.md 新:工具无关真源(agent 原生读 + Claude Code 经薄壳引入)
├── CLAUDE.md 改:薄壳(@AGENTS.md + <!-- Claude Code 专属 --> 逃生舱)
├── MEMORY/ 改:去品牌化(R4,结构与文件数不变)
└── .migration-backup/ 自动:原 CLAUDE.md + 迁移 / 覆盖率报告
Core design: thin-shell coexistence
AGENTS.md 唯一真源(工具无关,人工维护的唯一目标)
└── @MEMORY/MEMORY.md 记忆引入(写在 AGENTS.md 内,两边都能加载)
CLAUDE.md 薄壳(自动生成,不需要人工维护)
├── @AGENTS.md 引入全部共用内容
└── <!-- Claude Code 专属 --> 几行无法泛化的工具绑定内容(如有)
Information flow: Claude Code starts → reads CLAUDE.md → @AGENTS.md expansion → @MEMORY/MEMORY.md expansion;
reads AGENTS.md agent starts → reads AGENTS.md(native) → @MEMORY/MEMORY.md expansion.
Full layered model (L1 resident / L2 memory) andparagraph layering decision treesee
references/layering.md—read it when classifying paragraphs in Step 1.
Execution principles / boundaries
Rewrite rules R1–R5 (summary)
- R1 Tool-agnosticization: de-brand, do not change facts. Full replacement table (
Claude Code→AI coding agent、claude -p→agent CLI, etc., including the "when to keep tool names" criterion) seereferences/rewrite-rules.md—refer to it when rewriting in Step 2 / 3. - R2 @import location:
@MEMORY/MEMORY.mdwritten inAGENTS.md(not in CLAUDE.md). Claude Code via@AGENTS.mdrecursive expansion will definitely load it; whether other agents that readAGENTS.mdcan expand the internal@importis uncertain, but that line at least exists as an explicit pointer (seereferences/rewrite-rules.mdR2)。 - R3 Line width unchanged: the line width constraint observed in the original text (≤ 120 characters) continues to be observed after rewriting.
- R4 MEMORY rewriting: MEMORY body text is de-branded per R1; directory structure and file count remain unchanged.
- R5 Escape hatch: tool-specific content that cannot be generalized (e.g., scripts hardcoding
claude -psubprocesses), write the generalized version in AGENTS.md, and append the specific implementation at the end of the CLAUDE.md thin shell.Criterion: if the reader cannot perform the operation after removing the tool name → put it in the escape hatch.
Boundaries
- Do not touch permissions / MCP /
scripts/references/eval - Do not delete
CLAUDE.md(thin-shell coexistence); complete deletion requires explicit user confirmation - Do not generate agent-specific triggered rule files (
.qoder/rules/, etc.)—leave that to the user to configure in the target agent IDE - Idempotent: repeated runs overwrite the existing
AGENTS.md, without producing duplicate files
Workflow / Steps
Throughout: two places—the classification table (Step 1) and escape hatch content (Step 4)interactive confirmation points, do not decide silently.
Step 0: Pre-checks (run scripts/precheck.py)
python3 scripts/precheck.py <project-root>
Report whether CLAUDE.md is ready, whetherMEMORY/ exists, whether there is already AGENTS.md。
When there is already AGENTS.md , stop and let the user confirm overwriting, never overwrite silently.
Step 1: Snapshot + scan classification
- Snapshot the original
CLAUDE.mdto.migration-backup/CLAUDE.md.original—needed for Step 5 coverage comparison, this is theonly chance(Step 2 / 4 will rewrite / overwrite CLAUDE.md). - Parse
CLAUDE.mdall##paragraphs, run the layered decision tree ofreferences/layering.mdon each paragraph. - Output the classification table (paragraph → type → level → target file),show it to the user for confirmation / adjustmentthen continue.
Step 2: Generate AGENTS.md (LLM rewrite, core step)
- Organize the L1 content according to the AGENTS.md skeleton of
references/layering.md(project positioning / repository conventions / common commands / high-level structure / notes). - Add on the first line after the title
@MEMORY/MEMORY.md(R2)。 - Apply R1 (de-branding) + R3 (line width).
- Keep the total word count ≤ 1500 words (L1 budget); if exceeded, push detailed content down to L2 (
MEMORY/)。 - Self-check:
grep -iE "claude code|\.claude/" AGENTS.mdshould have no hits.
Step 3: Rewrite MEMORY (LLM, if present)
Apply R4: de-brand the MEMORY body per R1, keep the directory structure / file count unchanged.
Self-check:grep -riE "claude code|Claude Code|\bCC\b" MEMORY/ should have no hits (\bCC\b to avoid false positives on abbreviations).
Step 4: Generate the CLAUDE.md thin shell
According to the thin shell template of references/rewrite-rules.md : a "thin shell declaration" at the top (stating that
AGENTS.md is the single source of truth, do not edit shared parts here) + @AGENTS.md + <!-- Claude Code 专属 --> escape hatch
(TOOL_SPECIFIC content identified in Step 2, handled per R5). If there is no escape hatch content, omit the comment block.
Show the escape hatch content to the user for confirmation. Self-check: total line count ≤ 30,@AGENTS.md exists, the top contains the thin shell declaration, and there is no large body of text other than the declaration / @import / HTML comments.
Step 5: Coverage verification (run scripts/coverage.py)
python3 scripts/coverage.py <project-root>
Take the original CLAUDE.mdfrom the Step 1 snapshot, compare token by token line by line against AGENTS.md + thin shell CLAUDE.md
(built-in de-branding normalization, so that after Claude Code→agent it can still match), output the list of unmatched lines + coverage %.
Unmatched lines ≠ definitely lost——it may be de-branding rewrite or reasonable push-down; confirm with the user item by item whether it is lost or rewritten.
100% coverage is the goal. Finally run markdownlint to check that all new / modified files have 0 errors.
Reference example
This repository's own CLAUDE.md + MEMORY/ is a real, sufficiently complex fixture——run it end to end during eval
(see eval/evals.json). The skeleton templates (AGENTS.md skeleton, CLAUDE.md thin shell template) are respectively in
references/layering.md / references/rewrite-rules.md, Read as needed.