Update Agent Docs

Update Agent Docs

Claude Code port of the Codex update-agent-docs skill. AGENTS.md stays the documented target, including @CLAUDE.md-style include resolution; parallel discovery uses the Agent tool.

Purpose

Refresh the repository's agent-facing documentation so future sessions can find the right modules, packages, files, workflows, and tests without rediscovering the project from scratch.

Keep AGENTS.md as the token-efficient routing index. Put longer detail under docs/agent/ and make AGENTS.md point agents to those files on demand.

Required Workflow

1. Resolve the writable docs target.

   • Run the bundled resolver next to this SKILL.md: <skill-dir>/scripts/resolve_agent_docs_target.py <repo-root>.
   • Set agent_docs_target = result.target_path; every later instruction to edit AGENTS.md means edit this resolved target when it differs from result.agents_path.
   • If AGENTS.md is a symlink, edit the resolved target.
   • If AGENTS.md or its symlink target is a single include directive such as @CLAUDE.md, edit the included file.
   • If result.requires_confirmation is true, get explicit user confirmation before editing because the resolved target is outside the repository.
   • If the script reports a mixed or ambiguous include, inspect it and ask the user only if the source of truth cannot be determined safely.
   • If no AGENTS.md exists, create <repo-root>/AGENTS.md.

2. Read existing instructions before changing them.

   • Read the resolved target and any existing docs/agent/ files.
   • Preserve durable user preferences, repo-specific rules, and tool-routing rules.
   • Treat any recorded library, dependency, framework, runtime, or toolchain version as stale-prone guidance to replace with source-of-truth file routing.
   • Treat existing docs as input, not as complete coverage.
   • If the target already has substantial content, use a refresh stance: identify missing, stale, bloated, and duplicated guidance before rewriting.
   • Do not replace user-authored guidance wholesale unless it is demonstrably stale or the user asked to start fresh.

3. Use repository-aware retrieval.

   • Activate the repo with Serena when available and read Serena initial instructions if not already done.
   • Use Serena symbolic tools for source-code structure.
   • Use rg/rg --files through the repo's command wrapper when direct command output will stay small.

4. Launch multiple agents in parallel.

   • If subagent tooling is available and permitted by the current session policy, spawn independent agents before writing final docs. In Claude Code, use the Agent tool (one call per slice, dispatched in the same message so they run in parallel) when it is callable; otherwise search for the available multi-agent or subagent tool. Use subagent-prompts.md.
   • Assign distinct slices: architecture/module map, workflows/tests, frontend/UI, backend/API/data, infra/config/CI, and existing-doc gap review.
   • If subagent tooling is unavailable or the current tool policy forbids delegation without an explicit user request, report that the parallel-agent step cannot be performed and continue with careful single-agent discovery.

5. Explore beyond current docs.

   • Use discovery-checklist.md to cover manifests, source roots, entrypoints, scripts, tests, config, CI, deploy, generated assets, migrations, docs, and package boundaries.
   • Compare findings against the existing agent_docs_target; add missing categories even if the previous docs did not mention them.
   • Read other AI-agent configuration files when present and migrate only durable, repo-relevant guidance.
   • Ask the user only for practices the repo cannot reveal: non-obvious team conventions, required local services, branch/PR etiquette, test quirks, or changed workflows.

6. Write token-efficient docs.

   • Use doc-structure.md.
   • Before keeping a line in agent_docs_target, test it: would removing this cause a future agent to make a likely mistake? If not, cut or move it to docs/agent/.
   • Keep agent_docs_target concise but specific: mention exact folders/files to read for each common task.
   • Put detailed maps, workflow notes, and inventories in docs/agent/.
   • Prefer "When working on X, read Y first" guidance over prose summaries.
   • Do not write specific library, dependency, framework, runtime, or toolchain versions in AGENTS.md or docs/agent/, including versions copied from existing docs.
   • Instead, tell agents to check the project-managed source of truth for current versions, such as manifests, lockfiles, toolchain files, Dockerfiles, or CI config (package.json, lockfiles, pyproject.toml, requirements*.txt, go.mod, Cargo.toml, Gemfile, composer.json, .nvmrc, .python-version, .tool-versions, mise.toml, and similar files when present).
   • Keep personal preferences, private paths, secrets, and user-specific local setup out of shared docs unless the repository already intentionally documents them.

7. Verify.

   • Re-read changed docs for broken links, stale paths, duplicated sections, and unclear routing.
   • Run the narrowest useful check, usually link/path existence checks plus git diff --check.
   • If scripts or generated docs were changed, run the relevant validation or smoke check.

8. Ask about commit and push.

   • After verification, ask whether the user wants to commit and push to origin.
   • If the user agrees, follow commit-push-policy.md.
   • Do not add Co-Worker, Co-Authored-By, or similar attribution trailers to the commit message.

Output Expectations

• AGENTS.md or its resolved source-of-truth target is updated or created.
• docs/agent/ contains detailed supporting docs when detail would make AGENTS.md too large.
• The final response summarizes changed files, verification performed, and asks about commit/push when changes are complete.

Resource Map

• scripts/resolve_agent_docs_target.py: determine whether to edit AGENTS.md, its symlink target, or its single include target.
• references/discovery-checklist.md: complete project discovery checklist.
• references/doc-structure.md: recommended AGENTS.md and docs/agent/ structure.
• references/subagent-prompts.md: parallel subagent assignments and synthesis rules.
• references/commit-push-policy.md: exact commit/push behavior.