SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsagents-md-ssot

agents-md-ssot

Agents & models

View repository

Updated 10-16 09:44

About this skill

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

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, which Claude Code and agents that read AGENTS.md (such as Qoder) each load 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. Qoder is a typical target—itnatively reads AGENTS.md（official Rules documentationoriginal 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 with Qoder in a single step.@MEMORY/MEMORY.md is written in AGENTS.md (R2), and on the Claude Code side, recursive @ expansion will definitely load the memory index.

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 Qoder, or wants both 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 Qoder-recognizable 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 / rules)
  • Delete CLAUDE.md—this skill keeps the thin shell coexisting; if the user wants pure Qoder and to completely delete CLAUDE.md, explicit confirmation is required
  • Migrate to an agent other than Qoder—this skill targets Qoder's native reading of AGENTS.md + .qoder/rules/ mechanism; other agents (Cursor / Windsurf / Codex) have different context conventions, and the rewrite rules and destinations must be set up separately
  • Build project context from scratch(no existing CLAUDE.md)—there is no source to migrate; just write AGENTS.md directly, and the rewrite process is not needed

Input / Output

Input

Input Required Description
Project root directory Yes Defaults to cwd; must contain CLAUDE.md
MEMORY/ No If present, de-brand it as well (Step 4); if absent, skip
Original CLAUDE.md snapshot Automatic Step 1 automatically snapshots to .migration-backup/CLAUDE.md.original, for Step 6 coverage comparison

Output

<project-root>/
├── AGENTS.md                 新：工具无关真源（Qoder 原生读 + Claude Code 经薄壳引入）
├── CLAUDE.md                 改：薄壳（@AGENTS.md + <!-- Claude Code 专属 --> 逃生舱）
├── MEMORY/                   改：去品牌化（R4，结构与文件数不变）
├── .qoder/rules/*.md         可选：按需拆出的触发式规则（Step 3，可为 0 个文件）
└── .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 expands → @MEMORY/MEMORY.md expands; Qoder starts → reads AGENTS.md(native) → @MEMORY/MEMORY.md expands → .qoder/rules/*.md loads by type.

Complete layered model (L1 resident / L2 on-demand / L3 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: remove branding, don't change facts. Complete 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—compare against it when rewriting in Step 2 / 3 / 4.
  • R2 @import location：@MEMORY/MEMORY.md written inside AGENTS.md (not in CLAUDE.md), on the Claude Code side it is always loaded via @AGENTS.md recursive expansion; whether the Qoder side can expand @import inside AGENTS.md is not officially documented (see the boundary note in references/qoder-rules-format.md §1).
  • R3 Line width unchanged: the line width constraint the original text follows (≤ 120 characters) continues to be followed after rewriting.
  • R4 MEMORY rewriting: the MEMORY body is de-branded per R1; the directory structure and file count remain unchanged.
  • R5 Escape hatch: tool-specific content that cannot be generalized (such as scripts hardcoding the claude -p subprocess), write a generalized version in AGENTS.md, and append the specific implementation at the end of the CLAUDE.md thin shell.Criterion: after removing the tool name, the reader cannot perform the operation → put it in the escape hatch.

About .qoder/rules/ honest boundaries (important)

Qoder official documentationonlydescribes selecting rule type via IDE UI(Settings → Rules → Add) (Always Apply / Model Decision / Specific Files / Apply Manually);.qoder/rules/*.md of disk frontmatter format is not publicly documented. Therefore:

  • This skill'smain path does not depend on rule frontmatter——AGENTS.md itself to make the project Qoder-compatible.
  • Step 3 splitting .qoder/rules/ is anoptional optimization: do it only when the content truly needs to be triggered for loading by file / scenario.
  • The frontmatter of the split-out rule files writes only description(the most stable common subset);rule type is set by the user in the IDE UI, this skill does not fabricate trigger: fields, and only notes the suggested type for each file in the migration report.
  • The rule body is plain natural language—no images, no markdown links(Qoder does not parse links); the total characters of all rule files ≤ 100,000 (truncated if exceeded); in case of conflict, rules take priority over AGENTS.md。

Complete Qoder mechanisms (uses of the 4 rule types, 100k budget, priority with AGENTS.md,.qoder/rules/ splitting details) see references/qoder-rules-format.md—read it when deciding in Step 3 whether to split and how to split.

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 fabricate Qoder frontmatter fields that are not documented
  • Idempotent: repeated runs overwrite existing AGENTS.md / rules, without producing duplicate files

Workflow / Steps

Throughout the whole process: the classification table (Step 1), rule splitting (Step 3), and escape hatch content (Step 5), in three placesinteractive 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, and whether there is already AGENTS.md / .qoder/rules/。 When there is already AGENTS.md , stop and let the user confirm overwriting, never overwrite silently.

Step 1: Snapshot + scan and classify

  1. Snapshot the original CLAUDE.md to .migration-backup/CLAUDE.md.original—needed for the Step 6 coverage comparison, this is theonly chance(Step 2 / 5 will rewrite / overwrite CLAUDE.md).
  2. Parse all CLAUDE.md sections of ## , and run references/layering.md 's layered decision tree on each section.
  3. Output the classification table (section → type → layer → target file),show it to the user for confirmation / adjustmentbefore continuing.

Step 2: Generate AGENTS.md (LLM rewrite, core step)

  1. Organize the L1 content according to references/layering.md 's AGENTS.md skeleton (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 (.qoder/rules/）。
  5. Self-check:grep -iE "claude code|\.claude/" AGENTS.md should have no hits.

Step 3: Optional—split .qoder/rules/（LLM）

First determine whether to do it: split only when some content truly needs to be "loaded on a per-file / per-scenario trigger" (rather than resident in every session); if unsure,do not split——AGENTS.md has already made the project compatible; L2 is a pure gain, not required. When doing it, follow references/qoder-rules-format.md 's splitting details: group by topic, one .qoder/rules/collaboration-<scope>.mdper group, apply R1, body text in pure natural language with no links, frontmatter contains only description, and record each file's suggested rule type in the migration report for the user to set in the IDE.Let the user confirm the number of files and the type.

Step 4: Rewrite MEMORY (LLM, if present)

Apply R4: de-brand the MEMORY body according to R1, keeping the directory structure / file count unchanged. Self-check:grep -riE "claude code|Claude Code|\bCC\b" MEMORY/ should have no hits (\bCC\b avoids false positives on abbreviations).

Step 5: Generate the CLAUDE.md thin shell

According to references/rewrite-rules.md 's thin-shell template: at the top a "thin-shell declaration" (stating that AGENTS.md is the single source of truth and that the shared parts must not be edited here) + @AGENTS.md + <!-- Claude Code 专属 --> escape hatch (the TOOL_SPECIFIC content identified in Step 2, handled according to R5). If there is no escape hatch content, omit the comment block. Self-check: total line count ≤ 30,@AGENTS.md exists, the top contains the thin-shell declaration, and apart from the declaration / @import / HTML comments there is no large block of body text.

Step 6: Coverage verification (run scripts/coverage.py）

python3 scripts/coverage.py <project-root>

Take the original CLAUDE.mdfrom the Step 1 snapshot, compare line by line by token against AGENTS.md + .qoder/rules/ + thin shell CLAUDE.md (built-in de-branding normalization, so that Claude Code→agent can still match), output the list of unmatched lines + coverage %. Unmatched lines ≠ definitely lost—it may be de-branding rewriting or reasonable downscoping; confirm item by item with the user whether it is a loss or a rewrite. 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—use it for an end-to-end run during eval (see eval/evals.json). Skeleton templates (AGENTS.md skeleton, CLAUDE.md thin-shell template,.qoder/rules/ file templates) are respectively in references/layering.md / references/rewrite-rules.md / references/qoder-rules-format.md; Read as needed.