docs-sync

Keep README.md and AGENTS.md true to the code, short, and each in its own lane.

Two readers, two files:

• README.md is for people: what this is, how to install it, how to use it, where to go next. It is the front door.
• AGENTS.md is for coding agents: the commands, conventions, boundaries and gotchas an agent cannot infer from the code. It is read on every task, so every line costs tokens on every run.

Research backs the hard line here. Agent files generated by an LLM that restate the README made agents slightly worse and 20% more expensive; hand-curated files with only non-obvious, verified facts helped (see references/sources.md). So this skill writes few lines, checks every one, and deletes as readily as it adds.

Talk to the user in their language. Write each doc in the language it is already written in. A new file follows the README's language (translate the templates in references/, headings included); with no README, use the user's language.

Modes

Scope defaults to both root files plus any nested AGENTS.md/README.md for the packages the change touched. Narrow it when the user names one file.

1. Look before touching

git -C <root> status --short -- '*.md'
python3 <skill-dir>/scripts/docs_audit.py <root>

• Uncommitted edits to a doc you will change: the user may be mid-edit. Ask, or work around their lines; never overwrite them.
• The script prints the inventory (stack, package manager from the lockfile, every script/target/recipe, CI run steps, env example vars, version pins, agent files and how they link), the changes since each root doc was last committed (grouped by kind: manifests, env, CI, lint/test config, entry points, schema), and drift. Drift is mechanical; it finds dead commands and links, not wrong prose. Treat every line as a lead to confirm, not a verdict.

Then read every doc in scope in full, and read the sources of truth the docs describe: the manifests, the CI workflow (the commands CI runs are the ones that work), .env.example, and for an update the diff since the doc's last commit (git log --stat <sha>..HEAD, then git diff on the files the triggers named). Also grep tests and CI for strings copied from the README (badges, install lines, doc tests) before renaming or moving a section.

2. Build the fact list

Before writing a line, list the facts each doc will state, each marked:

• verified: seen in a manifest, config, CI step, code, or by running it
• inferred: likely but not proven (say how you would prove it)
• unknown: only the user knows (why a rule exists, deploy process, team etiquette, history behind a gotcha)

Only verified facts go in as plain statements. Inferred facts get checked now (read the code, run the --help) or left out. Unknowns become at most three questions for the user at the end, or, if the user asked you not to stop, a clearly marked <!-- TODO(docs-sync): confirm ... --> comment. Never invent a command, flag, URL, badge, version, number or claim.

3. Decide where each fact lives

One home per fact. Link instead of repeating. When README and AGENTS.md both need a fact, it lives in one and the other points to it.

Content in the wrong file moves (with a link left behind); it is not deleted. In a routine update, move only what the current change touches; list other misplaced content in the report as a suggestion. Restructure the whole file only when the user asked for a cleanup.

4. Update README.md

Follow references/readme.md for the sections by project type (library, CLI, app, service, monorepo) and the writing rules. The ones that matter most:

• Smallest accurate edit. Fix what is wrong, add what is missing for a real reader, keep the author's structure, voice, headings, badge style and anything they clearly like. Rewrite whole sections only when most of the section is wrong; rewrite the file only when asked or when it is a stub.
• Order of work: things that are false (commands, versions, paths, env vars, renamed features) → things that are missing for the reader (a new feature, a new required env var, a new install step) → things that are in the wrong file → polish. Stop when the next edit would be taste.
• Quick start must run. Install and the first command come from the manifests and CI, with the right package manager. When it is cheap and safe, run it (or --help) to confirm.
• No coverage padding. Don't add a section because a template has one. Skip Contributing/License prose when CONTRIBUTING.md / LICENSE exist: one link line each.
• Relative links, language tags on code fences, env vars by name only (never a value), no marketing filler.

5. Update AGENTS.md

Follow references/agents-md.md for the template, tool-by-tool interop and nesting rules. The core:

• The inclusion test for every line, new or old: would an agent make a mistake without it? If the agent could learn it by reading the code, the manifest, or the linter config, leave it out. No directory trees, no file-by-file tours, no "write clean code", no restating the README, no linter rules (the linter enforces them), no task history, no secrets.
• Commands are exact and verified: copied from the manifest or CI, with the right package manager, preferring the fast single-file/single-test form. A table is fine.
• Prune as you add. Remove what the drift report proved stale, what contradicts another line or file (agents follow either side at random), what duplicates the README, and generic advice. An update that only appends is a bug.
• Budget: aim for under ~100 lines; 150 is a soft ceiling and 200 the hard one. Past that, move package-specific rules to nested AGENTS.md files and long references to docs/ with a pointer ("Before touching billing, read docs/billing.md").
• Boundaries in three short lists when the repo needs them: always do / ask first / never do.
• New rules need evidence. Add a rule only when the repo proves it (config, CI, code, a repeated mistake the user pointed out) or the user states it. Write it at the narrowest scope that holds (nested file over root).

One source for every agent

AGENTS.md is the source of truth. Other agents' files point to it instead of copying it:

• CLAUDE.md: @AGENTS.md on its first line, plus only Claude-specific notes below it. A symlink also works, but breaks on some Windows checkouts. Claude Code skips AGENTS.md when a CLAUDE.md or CLAUDE.local.md exists without importing it, so the import line is what keeps them joined.
• Existing CLAUDE.md with real content and no AGENTS.md: move the content to AGENTS.md (pruning it on the way) and leave the import in CLAUDE.md. Tell the user; this is a structural change, so confirm first when the file is shared by a team.
• Generated blocks between markers (e.g. <!-- BEGIN:nextjs-agent-rules -->, written by next dev) stay byte for byte. Move one only to the file its generator writes to (read the generator), or it comes back as a diff.
• GEMINI.md, .github/copilot-instructions.md, .cursor/rules: reduce to a pointer or tool-only rules when they duplicate AGENTS.md. If the repo syncs them with a generator (rulesync, Ruler...), edit the generator's source, not the outputs.

6. Create a missing file

• README.md: from the inventory and code only. The title, a one-line description (matching the manifest description when there is one), quick start, usage, and the sections references/readme.md lists for the project type. Unknowns become TODO comments or questions, never filler.
• AGENTS.md: start from the template in references/agents-md.md and fill only the sections the repo gives verified facts for; drop empty ones. A 15-line file of true, non-obvious facts beats a 150-line generated one. Then ask the user for the things only they know (gotchas, ask-first operations, PR rules), at most three questions.
• CLAUDE.md when AGENTS.md is new and no CLAUDE.md exists: create it with the single line @AGENTS.md. It costs nothing and makes every Claude Code version load AGENTS.md. Skip it only if the user says they don't use Claude.

7. Verify

python3 <skill-dir>/scripts/docs_audit.py <root>

The drift you fixed must be gone, with no new lines. Then:

• Run the cheap, safe commands you documented (--help, lint, typecheck, a single test). Never run anything that deploys, migrates, publishes, sends email or charges money.
• Re-read each changed doc top to bottom as its reader: a newcomer for the README, an agent with no context for AGENTS.md.
• git diff --stat on the docs: an AGENTS.md that only grew is a warning sign.

8. Report

Short, in the user's language:

Docs atualizados: README.md (412 → 398 linhas), AGENTS.md (criado, 46 linhas), CLAUDE.md (→ `@AGENTS.md`).
 
- README: corrigi `npm run start:dev` → `pnpm dev`; adicionei `STRIPE_WEBHOOK_SECRET` à config; movi o guia de deploy para docs/deploy.md.
- AGENTS.md: comandos do CI, regra de migrations (ask first), arquivos gerados em src/gen/.
- Verificado: audit sem drift, `pnpm lint` e `pnpm test -- auth` passam.
- Não verifiquei: <x>.
 
Preciso de você: <até 3 perguntas, com sua recomendação>.

Don't commit. Offer to, following the repo's commit style.

Rules

• Never invent commands, flags, links, badges, versions, benchmarks or features. Unverified means left out, asked, or marked TODO.
• Never paste secrets or real env values; names only.
• Never delete content that might matter to someone; move it and link it.
• Never overwrite the user's uncommitted doc edits.
• Keep the author's voice and structure; the goal is accuracy, not a makeover.
• Audit mode changes nothing.