ia-md-docs

Manages project documentation: CLAUDE.md, AGENTS.md, README.md, CONTRIBUTING.md, DOCS.md. Use when asked to update, create, or init these context files. Not for general markdown editing.

Markdown Documentation

Manage project documentation by verifying against actual codebase state -- analyze structure, files, and patterns before writing; never generate blind.

Portability

AGENTS.md is the universal context file (works with Claude Code, Codex, Kilocode). During Initialize Context or Update Context Files workflows only: if CLAUDE.md exists without AGENTS.md, confirm with the user first (Ask via AskUserQuestion (Claude Code; load with ToolSearch select:AskUserQuestion if not loaded) or request_user_input (Codex); fall back to numbered options in chat), then mv CLAUDE.md AGENTS.md && ln -sf AGENTS.md CLAUDE.md. Never migrate as a side effect of another task.

When this skill references "context files", it means AGENTS.md (and CLAUDE.md if present as symlink).

Workflows

Update Context Files

Verify and fix AGENTS.md against the actual codebase. See update-agents.md for the full verification workflow.

1. Read existing AGENTS.md, extract verifiable claims (paths, commands, structure, tooling)
2. Verify each claim against codebase (ls, cat package.json, cat pyproject.toml, etc.)
3. Fix discrepancies: outdated paths, wrong commands, missing sections, stale structure
4. Discover undocumented patterns (scripts, build tools, test frameworks not yet documented)
5. Report changes

Update README

Generate or refresh README.md from project metadata and structure. See update-readme.md for section templates and language-specific patterns.

1. Detect language/stack from config files (package.json, pyproject.toml, composer.json)
2. Extract metadata: name, version, description, license, scripts
3. If README exists and --preserve: keep custom sections (About, Features), regenerate standard sections (Install, Usage)
4. Generate sections appropriate to project type (library vs application)
5. Report changes

Update CONTRIBUTING

Update existing CONTRIBUTING.md only -- never auto-create. See update-contributing.md.

When updating, detect project conventions automatically:

• Package manager from lock files (package-lock.json → npm, yarn.lock → yarn, pnpm-lock.yaml → pnpm, bun.lockb → bun)
• Branch conventions from git history (feature/, fix/, chore/ prefixes)
• Test commands from package.json scripts or pyproject.toml

Merge advisory. When CONTRIBUTING.md sits next to an AGENTS.md (repo root or any package root), surface a one-line recommendation: merge the contribution workflow section into the sibling AGENTS.md so the context file owns dev workflow, branch conventions, and review process as a single source of truth. Then suggest the user delete CONTRIBUTING.md after the merge. Never auto-merge and never auto-delete -- the user performs both. Continue the requested workflow regardless; the CONTRIBUTING file is advisory only.

Update DOCS

If DOCS.md exists, treat it as API-level documentation (endpoints, function signatures, type definitions). Verify against actual code the same way as AGENTS.md. Never auto-create DOCS.md -- only update existing.

When a doc prescribes a machine-consumed shape (a JSON artifact, config file, or request body) that code then validates, the two drift silently and each drift costs one caller a rejected write. A test that greps the doc for key names is a second copy of the doc: it goes green when both copies are wrong together, which is the only failure that matters. Have the tool report its validators' key sets as a versioned subcommand, sourced from the same constants the validators read — a constant only the report reads is decoration — then compare the doc against that report in both directions: a documented key no validator accepts, and a required key no example shows. Guard the guard: an example nothing can classify is a failure rather than a skip, and a validated artifact with no example is a failure.

• Assert nested rows separately -- a walk over top-level examples cannot reach a row inside an array.
• Assert field order when the doc's order is how a reader learns the shape.
• Run the comparison against the installed binary as well as the build tree.

Initialize Context

Create AGENTS.md from scratch for projects without documentation. See init-agents.md.

1. Analyze project: language, framework, structure, build/test tools
2. Generate terse, expert-to-expert context sections
3. Write AGENTS.md, create CLAUDE.md symlink

What Belongs in Context Files

Keep AGENTS.md / CLAUDE.md to durable signal. Do NOT enumerate:

• Installed skills, plugins, or extensions -- these change with the user's environment, not the project; the list rots within weeks.
• Tool versions outside the project's source of truth -- package.json engines, .nvmrc, pyproject.toml Python constraint, composer.json PHP version. List the source-of-truth file path; do not duplicate the version inline.
• Linter / formatter rule restatements -- if .eslintrc, ruff.toml, phpcs.xml already enforce it, the file is the spec. List the command to run; do not paraphrase rules.
• README content -- if information is already in README.md (install, badges, intro), reference it; do not re-paste.

The test: if a fact will be wrong in two months without anyone touching this file, it does not belong here.

What earns the space is the inverse: document what the agent cannot discover by reading the repo -- the unwritten convention, the reason behind a choice, the gotcha no config file confesses. The environment is a source of truth too, so a section restating it is a cache, and a cache earns its load only when the lookup is expensive. Naming the one test command among forty package.json scripts is an expensive lookup and belongs here (see Commands below); a raw ls -R dump or a paraphrase of --help is a cheap one the agent can re-derive on demand. A curated structure note -- what a new top-level directory is for -- is not the same thing, and still belongs here.

Treat fewer words as an optimization signal, not an acceptance criterion. Before condensing or merging rules in a context file, capture a baseline and predeclare the decisions the file exists to control: request authority, external actions, when to ask, proof standards, failure attribution. Compare baseline and candidate on the same cases; any safety, authority, or honesty regression rejects the candidate however much smaller it is. Prefer merging duplicated rules and deleting procedural restatement; preserve exact wording where it is what changes behavior. Change one rule group at a time, and add a case when a new failure mode appears rather than growing the file pre-emptively.

Context File Hierarchy

Structure CLAUDE.md (and AGENTS.md) content by priority so the most critical information loads first when context is compacted:

1. Rules -- project constraints, forbidden patterns, required conventions. Override everything else.
2. Tech stack -- languages, frameworks, package managers (versions: see above).
3. Commands -- how to build, test, lint, deploy. Exact commands, not descriptions.
4. Conventions -- naming patterns, file organization, architectural decisions.
5. Boundaries -- what's off-limits, what requires approval, scope constraints.

Rules that prevent mistakes outweigh background information.

Monorepos

Multi-package repo? Read monorepo.md before any update-*/init-* sweep (discovery commands, per-file scoping, context-loading rules). Enumerate targets; if the sweep would create or rewrite more than 3 files, stop: list planned targets and confirm before writing (same ask mechanism as in Portability above).

Arguments

Treat these as user-request modifiers: apply when the request contains the flag or equivalent phrasing. All workflows support:

• --dry-run: preview changes as a diff, write nothing
• --preserve: keep existing structure, fix inaccuracies only
• --minimal: quick pass, high-level structure only
• --thorough: deep analysis of all files

Backup Handling

Before overwriting: cp FILE FILE.backup; never auto-delete backups.

Writing Style

• Lead with the answer. First sentence of each section states the conclusion; reasoning follows. No "In this section, we'll..." preamble.
• Imperative form for instructions: "Build the project" not "The project is built" — verify no passive voice in any directive sentence.
• One directive per sentence. A rule that bundles two actions gets half-applied: the reader acts on the first clause and the last, and drops the middle. Move any sequence of 3+ steps into a numbered list rather than burying it in prose.
• must/never for requirements, should/may for latitude. A requirement phrased as "should" reads as optional and gets skipped.
• Expert-to-expert: cut explanations of concepts the target reader already knows. For CLAUDE.md/AGENTS.md, assume familiarity with git, package managers, test runners, and the project's main language.
• Scannable: headings every ~20 lines, bullet lists for ≥3 parallel items, fenced code blocks for every command.
• Verify every command and path against the codebase. Run each command before committing; grep for each referenced path. Stale paths and untested commands are the most common doc defect.
• Verify every external identifier, not just internal paths. A cited upstream PR, issue, RFC, or release tag is a claim about someone else's repository: open it and confirm the title matches what the sentence says it is. Shorthand that merely looks canonical (PR-120, issue 99) is the usual failure — it gets treated as the real ID by everything downstream and fans out into every artifact built from that file. Write the canonical form (owner/repo#N), and re-verify state claims ("merged", "fixed in") before publishing, since those rot fastest. One lookup per cited ID is cheaper than correcting the same wrong link in N places after it ships.
• Sentence case headings, no emoji decoration in CLAUDE.md/AGENTS.md/CONTRIBUTING/DOCS; README headers may carry at most one conventional emoji per header (see ia-writing's README rules); changelog entries may use emoji per project convention.
• Actionable headings: "Set SAML before adding users" — not "SAML configuration timing". Reader should know what to do from the heading alone.
• Collapse depth with <details> blocks instead of deleting content (blank line required after <summary> for GitHub rendering).

README Anti-Patterns

Flag during Update README workflows:

• Framework-first lead (explaining the tech stack before the problem it solves)
• Jargon before definition (using project-specific terms without introduction)
• Theory before try (architecture explanation before a working example)
• Claims without evidence ("blazingly fast" with no benchmarks)
• Changelog-speak, in both directions -- forward-looking hype ("now supports", "new in 3.2", "coming soon") and backward-looking narration of a diff ("this replaced the previous approach", "X was refactored to use Y"). A README describes the tool's present tense; a reader without the commit history gets archaeology instead of a description. Version-migration notes belong in CHANGELOG or docs/, and CHANGELOG, release notes, migration guides, and decision records are exempt -- being version-scoped is their purpose

Report Format

After every operation, display a summary:

text

[OK] Updated AGENTS.md
  - Fixed build command
  - Added new directory to structure

[OK] Updated README.md
  - Added installation section
  - Updated badges

[--] CONTRIBUTING.md not found (skipped)

Verify

• Every factual claim in updated docs verified against current codebase
• No stale file paths or component names
• Formatting renders correctly in markdown preview