SuperAPI AI Directory

claude-to-agents-ssot

Coding & development

View repository

Updated 10-16 09:30

About this skill

AGENTS.md as the single source of truth (CLAUDE.md thin-shell coexistence)

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 without MEMORY/), and you want to generate a cross-agent universal AGENTS.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.md agent—this skill's main path (generating a universal AGENTS.md) holds for any agent that reads AGENTS.md (Qoder / Codex, etc.); it is inapplicable only when the target agent does not read AGENTS.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 produces AGENTS.md + thin-shell CLAUDE.md + MEMORY/
  • Build project context from scratch(no existing CLAUDE.md)—there is no source to migrate, so just write AGENTS.md directly; 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) see references/rewrite-rules.md—refer to it when rewriting in Step 2 / 3.
  • R2 @import location:@MEMORY/MEMORY.md written in AGENTS.md (not in CLAUDE.md). Claude Code via @AGENTS.md recursive expansion will definitely load it; whether other agents that read AGENTS.md can expand the internal @import is uncertain, but that line at least exists as an explicit pointer (see references/rewrite-rules.md R2)。
  • 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 -p subprocesses), 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

  1. Snapshot the original CLAUDE.md to .migration-backup/CLAUDE.md.original—needed for Step 5 coverage comparison, this is theonly chance(Step 2 / 4 will rewrite / overwrite CLAUDE.md).
  2. Parse CLAUDE.md all ## paragraphs, run the layered decision tree of references/layering.md on each paragraph.
  3. 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)

  1. Organize the L1 content according to the AGENTS.md skeleton of references/layering.md (project positioning / repository conventions / common commands / high-level structure / notes).
  2. Add on the first line after the title @MEMORY/MEMORY.md(R2)。
  3. Apply R1 (de-branding) + R3 (line width).
  4. Keep the total word count ≤ 1500 words (L1 budget); if exceeded, push detailed content down to L2 (MEMORY/)。
  5. Self-check:grep -iE "claude code|\.claude/" AGENTS.md should 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.