readme-agents-doc

name	readme-agents-doc
description	Generates and idempotently updates high-quality README.md and AGENTS.md files for any repository. Runs a fixed step-by-step pipeline — a 4-phase recon pass (manifests → architecture → conventions → artifacts), a Purpose & Gotchas discovery phase, optional PR intelligence via gh, then heading-anchored template rendering for safe re-runs — stopping to ask the user at defined decision gates. Optionally leverages RTK for token compression, ast-grep for AST-aware code exploration, and gh for merged-PR context. Nests writing-clearly-and-concisely for prose quality.
license	MIT
metadata	{"version":"1.2.0"}

readme-agents-doc

Generate or refresh a project's README.md and AGENTS.md (and optionally CLAUDE.md) using a recon-first, idempotent, template-driven pipeline. Portable across agents that read Markdown skills.

When to use

• User asks to create, update, or refresh a README.md or AGENTS.md
• User wants to bootstrap agent instructions for a repository
• User wants a doc-drift check (report only, no writes)
• User wants a CLAUDE.md bridge that imports AGENTS.md

Execution contract

This skill runs as a fixed sequence, not as reference reading. Follow it exactly.

1. Track every phase. Before starting, create one todo per phase below (0 → 6). Mark it in-progress when you begin and completed only when its actions and any gate are done.
2. In order, no skipping. Run the phases in sequence. Do not batch, reorder, or drop one. If a phase is genuinely not applicable (e.g. Phase 3.5 under --offline), mark it completed with a one-line reason rather than skipping silently.
3. Load before acting. Load the references a phase lists before running that phase's actions. Never write prose before Phase 5 loads prose-standards.md.
4. Stop at every gate. A [GATE Gn] marks a decision that is the user's to make. When its trigger fires, STOP and use AskUserQuestion with the options shown, then act on the answer — never guess past it. When a script emits {"action":"prompt_user", …} or a questions plan on stdout, that is a gate: surface it.
5. Evidence before claims. Call a command working only after Phase 4 verified it. Call the run done only after Phase 6 passes (or the user overrode a failure at G4).

Gates — when to stop and ask

Gate	Fires when	Ask	Then
G0 · Update	Phase 0 check_update.sh reports update_available: true (installed copy is behind source main)	Reinstall the newer skill now, or continue on the current version?	On reinstall: run scripts/install.sh and restart the skill so the new version runs
G1 · Tools	Phase 0 preflight.sh emits a prompt_user action (a tool is missing)	Install rtk / ast-grep / gh, proceed with what's present, or skip?	Persist the choice to config.json; export RTK_MODE/SG_MODE/GH_MODE
G2 · Adoption	Phase 1 finds an existing README.md/AGENTS.md with none of the skill's headings	Merge sections in (preserve existing prose) / full replace / cancel	Record the choice; merge is the default. Give existing prose its own heading so it is preserved
G3 · Purpose	Phase 3 extract_purpose.py reports gaps (use_when, use_not_for, why-it-exists)	Run interview.py --plan, ask its questions one at a time, capture answers	Pipe answers back via interview.py --apply; merge into purpose.json
G4 · Verify	Phase 6 verify.py exits 2 (rubric failure) or 3 (secret)	Fix / override / abort (a secret at exit 3 is abort-only — rotate it)	Fix and re-verify, or write with an explicit override note

Design principles

• AGENTS.md is canonical. README.md is human-facing. CLAUDE.md is a thin @AGENTS.md import. No duplicated content.
• Recon before reasoning. Detect via Glob/Grep on manifests; never full-file reads during discovery.
• Enhance in place, never blind overwrite. Managed sections, tracked by their Markdown heading, preserve human-authored prose. See references/managed-regions.md.
• Why + Gotchas are required. Every generated file answers why this project exists and what surprises new users.
• Progressive disclosure. This file stays short. Deep guidance lives in references/.
• Optional tooling, graceful fallback. RTK, ast-grep, and gh add signal when present; skill works without them.

Optional tooling

Tool	Role	Detect	Install (macOS)
RTK	60-90% token savings on shell recon	rtk --version	brew install rtk
ast-grep (sg)	AST-aware structural code queries	sg --version	brew install ast-grep
gh	Merged-PR intelligence for purpose, gotchas, conventions	gh auth status	brew install gh + gh auth login

All three are opt-in. See references/rtk-integration.md, references/ast-grep-patterns.md, and references/pr-intelligence.md.

Nested skill

Prose quality is enforced by the nested skill at assets/writing-clearly-and-concisely/. See references/prose-standards.md for how it plugs into every prose-generating phase. All README bodies, purpose paragraphs, gotcha descriptions, and feature bullets pass through its rules before write.

Workflow — 7 phases

Each phase is a step in the contract above. Run them in order; stop at the gates.

Phase 0 — Preflight

1. Run scripts/check_update.sh (best-effort; ignore if it reports checked:false). [GATE G0] If update_available is true, STOP and ask whether to reinstall now (scripts/install.sh) or continue on the current version.
2. Run scripts/preflight.sh. It reads .readme-agents-doc/config.json; if absent, it resolves each tool to on/off/prompt.
3. [GATE G1] If it emits {"action":"prompt_user", …}, STOP and ask the user which tools to install/use, then persist and re-run so the modes resolve.
4. Export RTK_MODE, SG_MODE, GH_MODE for downstream steps.

Load: references/rtk-integration.md, references/ast-grep-patterns.md, references/pr-intelligence.md (only the sections matching enabled tools).

Phase 1 — Audit

1. Read existing README.md, AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md, CI workflow files, and CHANGELOG.md.
2. Identify which section headings the skill owns (see references/managed-regions.md). Everything under a heading the templates don't own — and the title/intro preamble — is human-authored and must be preserved verbatim.
3. [GATE G2] If a target file exists but contains none of the skill's headings, STOP and ask: merge sections in (default, preserves prose) / full replace / cancel. Persist the choice.

Load: references/managed-regions.md

Phase 2 — Recon (Glob/Grep only)

Run scripts/inventory.py. Detects manifests, frameworks, entry points, top-2 directory levels, test/CI/lint configs. Uses scripts/sg_query.sh when ast-grep is available. Emits .readme-agents-doc/inventory.json.

Load: references/recon-workflow.md, references/stack-fingerprints.md, references/command-recipes.md Load if SG_MODE=on: references/ast-grep-patterns.md

Phase 3 — Purpose & Gotchas discovery

Run scripts/extract_purpose.py for the 3-pass discovery:

1. Pass 1 — Existing signals: README intro, manifest description, gh repo view (if GH_MODE=on), commit messages, CHANGELOG.md.
2. Pass 2 — Structural signals: TODO/FIXME/HACK/XXX/WARNING comments, deprecation markers (via ast-grep when available), warn/panic messages, feature flags, env-var checks.
3. Pass 3 — Targeted interview: [GATE G3] when Passes 1–2 leave gaps, run scripts/interview.py --plan, ask the user its questions (one at a time), and merge answers back with --apply. Uses references/interview-questions.md.

Emits .readme-agents-doc/purpose.json.

Load: references/purpose-and-gotchas.md, references/interview-questions.md

Phase 3.5 — PR intelligence (only if GH_MODE=on and repo has GitHub remote)

Run scripts/gh_intel.sh. Eight sub-passes:

• 3.5a — repo metadata baseline (gh repo view)
• 3.5b — recent merged PRs (last 90 days) for purpose evolution
• 3.5c — breaking changes and migrations (label-filtered)
• 3.5d — review-thread gotchas (grep for "gotcha", "note that", "watch out", "footgun")
• 3.5e — label taxonomy → convention detection
• 3.5f — commit message convention detection
• 3.5g — required CI checks
• 3.5h — release cadence (optional badge/version signal)

Emits .readme-agents-doc/pr-intel.json. Feeds pre-populated gotcha candidates back to Phase 3's interview. Skip under --offline (mark the phase done with that reason).

Load: references/pr-intelligence.md, references/gh-query-recipes.md

Phase 4 — Extract & verify commands

Run scripts/extract_commands.py to auto-pull build/test/lint commands from Makefile, package.json, pyproject.toml, go.mod, Cargo.toml, Gemfile. Run scripts/verify_commands.py to confirm each command exists (via --help probe). Classify architecture pattern. Trace one request end-to-end for the architecture blurb.

Load: references/stack-fingerprints.md

Phase 5 — Generate/Update

1. Before any prose is written, load references/prose-standards.md (which loads the nested writing skill).
2. Run scripts/render.py. Fills templates/README.md.tmpl and templates/AGENTS.md.tmpl from inventory.json + purpose.json + pr-intel.json. Idempotent: on re-run it rewrites only the sections it owns (matched by heading), preserves other sections and the preamble verbatim, and appends any newly-added template sections. Emits scoped AGENTS.md per detected subsystem. Emits CLAUDE.md bridge if --emit-claude-bridge is set.

Load: references/readme-anatomy.md, references/agents-md-spec.md, references/nested-scoping.md, references/example-outputs.md Load if bridging: references/claude-md-bridge.md

Phase 6 — Verify against rubric

Run scripts/verify.py. Checks:

• README has Hero, Why, Quickstart, Usage, Architecture, Gotchas, Dev, License
• AGENTS.md has Purpose, Build/Test, Style, Testing, Security, PR, Gotchas
• AGENTS.md ≤ 32 KiB (Codex cap); root files 100–200 lines
• No secrets (basic pattern scan)
• No README/AGENTS content duplication
• All referenced commands verified
• Prose passes signs-of-ai-writing.md scan (no puffery, no LLM tells)
• If RTK_MODE=on, reports rtk gain savings

[GATE G4] On exit 2 (rubric failure), STOP and ask: fix / override / abort. On exit 3 (secret detected), abort and tell the user to rotate it — never write.

Load: references/quality-rubric.md, references/anti-patterns.md, assets/writing-clearly-and-concisely/signs-of-ai-writing.md

Modes

• Default: generate/update all
• --drift-check-only: Phase 6 only, no writes; emit patch report
• --emit-claude-bridge: emit CLAUDE.md importing AGENTS.md
• --style thin|verbose: choose AGENTS.md template variant (thin ≤ 120 lines, verbose ≤ 200)
• --re-interview: force Phase 3 Pass-3 interview even if purpose.json exists
• --offline: skip Phase 3.5

First-time run vs re-run

• First run: none of the skill's section headings are present. At [GATE G2] the skill offers to merge its sections in (recommended — preserves existing prose under its own headings) or full replace. Persists the choice.
• Re-run: only sections whose headings the skill owns are re-rendered. Other sections and the title/intro preamble are preserved verbatim.

Artifacts

• README.md, AGENTS.md (root, plus per-subsystem scoped files in monorepos)
• CLAUDE.md (optional, one-line @AGENTS.md + Claude-specific extras)
• .readme-agents-doc/config.json (tool preferences, gitignore-friendly)
• .readme-agents-doc/inventory.json, purpose.json, pr-intel.json (recon cache)
• .readme-agents-doc/drift-report.md (only if --drift-check-only)

Installing / updating the skill

• Install (or reinstall) with scripts/install.sh [SOURCE_REPO] [DEST_DIR]. It copies the tree into ~/.claude/skills/readme-agents-doc and writes .install-meta.json (source path + installed commit SHA + version).
• scripts/check_update.sh reads that metadata, fetches the source's origin/main, and reports whether the install is behind — this backs [GATE G0]. Bump metadata.version above whenever behavior changes.