agents-to-claude-md

name

agents-to-claude-md

description

Scans the current repo for AGENTS.md files, finds directories that lack a matching CLAUDE.md, translates each AGENTS.md to a CLAUDE.md draft (applying the Codex→Claude substitution table), runs a /where-claude sanity check per candidate, and — with per-item approval — either writes the translated draft or invokes /init inline for a richer code-derived doc. Never overwrites an existing CLAUDE.md. Global and project-agnostic. Trigger when the user says "agents to claude md", "bootstrap claude md from agents md", "create claude md from agents md", "convert agents md to claude md", "init claude md from agents", "port agent docs to claude", or "agents-to-claude-md".

agents-to-claude-md

Global, project-agnostic skill. It finds every AGENTS.md in the current repo, identifies directories that have no matching CLAUDE.md, translates each source file using the Codex → Claude substitution table, and — with per-item approval — writes the draft or invokes /init inline for a richer code-derived alternative.

Use when: you've opened a Codex-first repo in Claude Code and there are zero or few CLAUDE.md files; the existing AGENTS.md files already describe the directory's purpose and conventions, so translation is a near-free win over starting from scratch.

Procedure

1. Scan

find . -name AGENTS.md \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/vendor/*' \
  -not -path '*/.venv/*'

Also detect AGENTS.override.md files with a parallel find. Keep them in a separate list — they will be reported but not translated (no CLAUDE.override.md equivalent exists in Claude Code).

2. Compute the gap

For each <dir>/AGENTS.md found, check whether <dir>/CLAUDE.md already exists. Separate results into three buckets:

• Gaps — directory has AGENTS.md but no CLAUDE.md (action candidates)
• Already in sync — both files exist (skip silently)
• Override-only — directory has only AGENTS.override.md, no AGENTS.md (skip with note)

If there are no gaps, report "All directories with AGENTS.md already have a CLAUDE.md — nothing to do." and stop.

Present the gap list before doing anything else:

Directories with AGENTS.md but no CLAUDE.md
  - src/backend/     (AGENTS.md: 34 lines)
  - scripts/         (AGENTS.md: 12 lines)

Already in sync (skipped)
  - .               (both files exist)

Skipped — no Claude equivalent
  - .github/         (AGENTS.override.md only — create CLAUDE.md manually if needed)

Ask the user which items to act on. Do not proceed without explicit per-item approval.

3. /where-claude sanity check (per approved candidate)

Before presenting the translated draft for a given directory, apply the /where-claude scoring heuristic as a quick sanity check.

Positive signals (the directory likely warrants its own CLAUDE.md):

• Has its own module manifest: package.json, pyproject.toml, go.mod, Cargo.toml, setup.py, *.csproj, pom.xml, etc.
• Uses a different language, framework, or build tool than the repo root.
• Has its own lint/format/test config or codegen fixtures.
• Contains ≥ 15 source files or is a clearly self-contained component.
• Sits at an architectural seam: services/<x>, packages/<x>, apps/<x>, cmd/<x>.

Negative signals (the directory may not need one):

• Tiny leaf dir with few files and no module boundary.
• Already fully described by an ancestor CLAUDE.md.
• Contains only assets, generated files, or vendored/dependency code.

If the directory scores negatively, warn before showing the draft:

"Warning: this directory may not warrant its own CLAUDE.md — it has no module boundary and a parent instruction file may already cover it. Proceed anyway?"

If it scores positively, note the signal in the approval prompt (e.g., "This directory has its own package.json — a CLAUDE.md here is well-motivated.").

4. Translate and get approval

Read the AGENTS.md and apply the substitution table in order:

Find	Replace with
AGENTS.md / AGENTS.override.md	CLAUDE.md
$<skill-name> invocation syntax	/<skill-name>
where-agents-md cross-references	where-claude
audit-agent-docs cross-references	audit-claude-md
Codex config paths (~/.codex/, $CODEX_HOME, .codex/)	Claude config paths (~/.claude/, .claude/)
"Codex" when referring to the product	"Claude Code"
"AGENTS" as a generic concept for instruction files	"CLAUDE.md"

Show the full translated draft to the user. For each item, offer two choices:

Option 1 — Write this translated draft as <dir>/CLAUDE.md Fast path; content mirrors the AGENTS.md. Best when the source is high-quality and detailed.

Option 2 — Invoke /init inline for this directory Claude invokes /init targeted at <dir> in this same session — no navigation needed. Produces a fresh, code-derived doc that may be richer than the translation. Best when the AGENTS.md is sparse or generic and the directory has substantial source code worth deriving context from.

Require an explicit choice (1, 2, or skip) before moving to the next item.

5. Write

On choice 1: write <dir>/CLAUDE.md with the translated content. Create intermediate directories if needed.

On choice 2: invoke /init with <dir> as the target directory. /init will analyze that directory's code and write its own CLAUDE.md; record the outcome in the wrap-up.

On skip: record the directory in the wrap-up; do not write anything.

6. Wrap-up

Report a summary in three sections:

Created (translated draft)
  <dir>/CLAUDE.md

Created (via /init)
  <dir>/CLAUDE.md

Skipped
  <dir>  — already existed
  <dir>  — user declined
  <dir>  — negative /where-claude signal, user chose not to proceed

Note: CLAUDE.md files are picked up automatically in the next Claude Code session opened in that directory — no ./install.sh step or restart required.

Guardrails

• Never overwrite an existing CLAUDE.md. Skip with a per-item warning if the target already exists.
• Never modify the source AGENTS.md.
• Never write to global paths (~/.claude/, ~/.codex/).
• Never translate AGENTS.override.md — skip it with an explanatory note.
• Require explicit per-item approval before every write.
• Apply the /where-claude sanity check and surface the result in the approval prompt; never silently create a file in a directory that clearly does not warrant one.
• When the AGENTS.md is sparse or vague, surface this in the approval prompt and recommend option 2 (/init) over option 1.
• Create intermediate directories as needed, but only for approved writes.