Docs

Documentation

Author, audit, and maintain project documentation across every surface that matters: the agent hot path (CLAUDE.md, AGENTS.md, .claude/rules/), the human entry point (README.md), and the narrative tier (docs/). This is the single home for "make our docs good" work — bootstrapping a new project, refreshing docs after a sprint, writing a README that converts readers into users, or auditing the whole estate for drift.

This SKILL.md is a thin index. Detailed authoring rules live in rules/*.md and load on demand. Worked examples are in references/*.md. Literal scaffolding skeletons are in templates/*.md. Do not preload everything — load only what the current phase asks for.

---

Mode Detection

Parse $ARGUMENTS (first token) and route to one of four modes. A second token of --auto is a cross-cutting modifier (see below).

Mode	Default	Trigger
init		"init", "bootstrap", "scaffold", or $ARGUMENTS == "init" (no existing CLAUDE.md).
update	yes	Default when a CLAUDE.md already exists. "update", "sync", "refresh", "drift".
readme		"readme", "write a README", "audit the README", or $ARGUMENTS == "readme".
audit		"audit", "review the docs", "doc health check", or $ARGUMENTS == "audit".

--auto modifier — append to any mode token to enable the autonomous-workflow guardrails. Always passed by autonomous-workflow Phase 5 as Skill("docs", "update --auto"). When --auto is present, also load auto-update-loop.md before executing the mode's phases.

Disambiguation rule when no mode token is passed:

1. If ./CLAUDE.md does not exist → init.
2. Else if ./README.md does not exist and the user mentioned "README" → readme.
3. Else → update.

State the detected mode in one line before continuing:

Mode: update
Target: this repo

---

Shared Foundations (every mode loads these)

Regardless of mode, every run is governed by three rule files. Load them once on first need; do not reload them per phase.

File	What it gives you
rules/content-routing.md	The Content Routing Rubric — which surface owns which kind of content, and why.
rules/placement-resolver.md	The innermost-wins algorithm for picking the specific file (root vs nested CLAUDE.md, .claude/rules/ with paths:, etc.).
rules/writing-style.md	Google + Microsoft style highlights, plain-language rules, and the agent-readable docs pattern.

Then add the rule files specific to the mode:

Mode	Additional rules to load
init	claude-md.md, readme.md, docs-folder.md
update	drift-detection.md, claude-md.md
readme	readme.md
audit	All of the above, plus maintenance.md for CI lint stack guidance.

When invoked from a non-interactive caller (autonomous-workflow Phase 5) — passed as --auto — also load auto-update-loop.md. That rule adds four non-negotiable gates (hot-path budget, recurrence threshold ≥ 2, removed-rules ledger, optional ablation) plus the JSON run-summary contract the caller logs.

---

Mode: init — bootstrap docs from scratch

Use when a project has no Claude configuration and (optionally) no documentation. Produces a tiered setup sized to the project's complexity.

Phases

1. Detect existing config. Check for CLAUDE.md, .claude/, AGENTS.md, README.md, docs/. If any exist, ask via AskUserQuestion: Overwrite / Merge missing / Skip / Abort.
2. Triage complexity. Count source files, directories, monorepo packages, CI/CD presence. See references/archetypes.md for the small / medium / large thresholds and the per-tier file matrix.
3. Detect tech stack. Package manager (pnpm / npm / yarn / bun / poetry / cargo / go.mod), test framework, linters, monorepo signal (nx.json, turbo.json, pnpm-workspace.yaml).
4. Scaffold the tier's files. Use templates/claude-md.md, templates/readme.md, and the docs/* templates listed in rules/docs-folder.md.
5. Wire .gitignore. Add .claude/settings.local.json idempotently.
6. Summarize. Print a table of created files with line counts and audience.

Hard rules during init

• Route by kind, not by file pattern. Rules go to CLAUDE.md / .claude/rules/; narrative goes to docs/; marketing goes to README.md. See rules/content-routing.md.
• CLAUDE.md ≤ 200 lines. Anthropic's own threshold — beyond it, adherence drops measurably.
• README first viewport must answer what is this, does it solve my problem, can I trust it? See rules/readme.md for the above-the-fold checklist.
• Never duplicate content between CLAUDE.md, README.md, and docs/. Pick one owner; link from the others.

---

Mode: update — sync docs with the codebase

Use after work has landed on a branch. Detects drift, applies targeted fixes, and pushes new rules to the innermost-ancestor destination so the hot path does not bloat over time.

Argument parsing

Argument	Default	Effect
branch	yes	Compare current branch vs the default branch. Default for update.
recent [N]		Diff the last N commits (default 10).
paths <glob>		Limit the diff to <glob>. The Placement Resolver still decides destinations.
nested <dir>		Route all updates for changes under <dir> to <dir>/CLAUDE.md (scaffold if missing).
pattern <glob>		Discovery-driven — scan files matching <glob> for shared structure, emit one rule.
holistic		Run holistic-analysis refactor on each affected area before drafting docs updates.
dry-run		Preview only. Print proposed changes; do not write.
all		Full audit against the current codebase (no diff). Equivalent to audit mode for sync only.

Phases

1. Detect changes (see rules/drift-detection.md §1 for git diff commands and the area-classification table).
2. Read current docs — every CLAUDE.md, .claude/rules/*.md, docs/**/*.md, AGENTS.md. Build a map of what's documented today.
3. Drift analysis. Run deterministic checks first (dead paths, removed commands, broken @imports); then semantic checks (architecture claims, style claims, stale gotchas). See rules/drift-detection.md.
4. Holistic analysis (if holistic was passed) — see rules/drift-detection.md §4.
5. Generate updates. Each proposed change is classified by content kind, routed via content-routing.md, and placed via placement-resolver.md. Priority tiers: P0 stale fixes apply immediately; P1 new patterns ask for confirmation; P2 polish skips unless requested.
6. Apply (or dry-run report).
7. Summarize. Per-file table of changes plus a list of areas intentionally skipped because Claude can infer them.

Sub-modes inside update

• update nested <dir> — see rules/placement-resolver.md §4.
• update pattern <glob> — see rules/placement-resolver.md §5.

---

Mode: readme — write or audit a README

Use when the README is the asset under work. Two sub-modes detected from context:

• No README exists or user says "write a README" → scaffold mode.
• README exists and user says "audit / review / improve" → audit mode.

Scaffold sub-mode

1. Detect tech stack and project type (library / app / monorepo root / CLI tool).
2. Render templates/readme.md with the structure from the standard-readme spec — see rules/readme.md for the mandatory section order and the badge selection rules.
3. Apply the above-the-fold checklist before declaring done — the first viewport must carry name, one-line tagline, hero visual or demo, primary CTA badges, and one install line.

Audit sub-mode

1. Read the README.
2. Run the README audit rubric in rules/readme.md §4. Score each item PASS / WARN / FAIL with one line of evidence.
3. End with a prioritized Top 3 fixes list — biggest reader-time wins first.

---

Mode: audit — comprehensive documentation health check

Read-only by default. Produces a structured report covering every doc surface.

Phases

1. Inventory. List every documentation file across the repo.
2. Per-surface audits:
   • CLAUDE.md and .claude/rules/ — see rules/claude-md.md §5.
   • README.md and any per-package READMEs — see rules/readme.md §4.
   • docs/ tree — see rules/docs-folder.md §3.
3. Drift checks — full set from rules/drift-detection.md §3 (dead paths, removed commands, broken @imports, hot-path leakage).
4. CI lint coverage — see rules/maintenance.md for the recommended markdownlint / Vale / alex / lychee stack.
5. Prioritized report. P0 (stale / wrong) → P1 (missing high-value content) → P2 (polish).

If the user asks to apply fixes, route to update mode with the audit findings as the input.

---

Definition of Done

Each mode has a closing gate. Treat any unchecked item as a defect.

init

• Tier picked and the per-tier files matrix matches the output.
• CLAUDE.md ≤ 200 lines.
• README.md first viewport (~600 px) carries name, tagline, hero, primary badges, install line.
• docs/ tree (medium / large only) has README.md, architecture.md, contributing.md, and (large only) per-package nested folders.
• .gitignore contains .claude/settings.local.json.
• No content is duplicated across CLAUDE.md, README.md, and docs/.

update

• Every P0 drift item from drift-detection.md §3 either fixed or explicitly skipped with reason.
• Every new rule placed via placement-resolver.md — no pattern-scoped rule landed in root CLAUDE.md.
• Every @import added resolves to a real file.
• No content moved into docs/ while a duplicate remains in CLAUDE.md (or vice versa).
• Summary table delivered.

readme

• All mandatory standard-readme sections present in correct order.
• Above-the-fold checklist passes.
• Badge count between 0 and 10, and every badge represents signal (build / version / license / coverage / security / contributors), not noise (stars / forks / "made with love").
• Every relative link resolves.

audit

• Every file in the inventory has a row in the report (PASS / WARN / FAIL or N/A).
• Top 3 fixes list at the end, ordered by reader-time impact.
• No file mutations — audit is read-only.

---

Core Principles

1. Right surface, right cost. CLAUDE.md is auto-loaded — every line is a recurring token cost. README.md is read once by humans evaluating the project. docs/ is loaded on demand. Route by these costs, not by what feels natural to write.
2. Innermost-wins. Nested CLAUDE.md files load only when the agent is in that subtree. A rule about packages/foo/** placed in packages/foo/CLAUDE.md costs zero tokens for someone in packages/bar/. The same rule in root costs everyone, every turn.
3. Be prescriptive, not descriptive. Tell the agent what to do; do not explain concepts. Decision tables and numbered lists beat prose.
4. Each document serves exactly one Diátaxis quadrant. Tutorial or how-to or reference or explanation. If a doc serves two, split it.
5. Never duplicate facts across surfaces. Pick one owner; link from the others. Duplicates always drift.
6. Test the docs by removal. "Would removing this cause Claude or a reader to make a mistake?" If no, delete it.

---

Anti-patterns (one-liner — full list in rules/ per surface)

• CLAUDE.md over 200 lines (Anthropic's own threshold — adherence drops).
• Pattern-scoped rule placed in root CLAUDE.md instead of .claude/rules/ with paths:.
• README wall-of-badges (>10 badges); TOC for a 60-line README.
• docs/ files unreferenced from anywhere (orphans).
• Same fact written in CLAUDE.md and docs/ — one will drift.
• Narrative paragraphs ("we picked X because Y, the system grew as Z…") in CLAUDE.md instead of docs/.
• Marketing prose ("blazingly fast," "simply," "easily") with no benchmark.
• README API reference dump — move to docs/.
• Backslash paths anywhere.
• Time-sensitive claims ("after August 2025…") in any surface.

---

Cross-tool note: AGENTS.md

agents.md is the cross-tool open spec read by Codex CLI, Cursor, Aider, Devin, GitHub Copilot, Gemini CLI, and others. Claude Code reads CLAUDE.md, not AGENTS.md directly.

Two interop options:

• Symlink — ln -s CLAUDE.md AGENTS.md (simplest; one source of truth).
• @import — keep both files but have CLAUDE.md start with @AGENTS.md and put shared content in AGENTS.md.

For mixed-tool teams, prefer the symlink. For Claude-Code-first teams with cross-tool readers as secondary, prefer the @import. See rules/claude-md.md §6 for the trade-offs.