Purpose

Updates README, AGENTS.md, changelogs, and handoff documents after a milestone or ticket completes. Ensures documentation surfaces stay synchronized with the actual state of the codebase so the next person (or agent) can resume without re-discovery.

When to use

• A milestone, sprint, or ticket just completed and docs may be stale.
• Someone asks to update README, AGENTS.md, CHANGELOG, or a START-HERE document.
• A handoff brief is needed for the next session, team, or agent.
• A PR merged significant changes and no doc update accompanied it.

Do NOT use when

• The task is writing or modifying application code — use an implementer skill.
• The task is verifying acceptance criteria — use

  qa-validation

  .
• The task is reviewing code quality — use

  code-review

  .
• The user wants to plan work, not document completed work — use

  planner

  .

Operating procedure

1. Run

   find . -maxdepth 3 -name 'README*' -o -name 'AGENTS*' -o -name 'CHANGELOG*' -o -name 'START-HERE*'

   to build a doc surface inventory.
2. Run

   git log --oneline --since="2 weeks ago" -- .

   to list recent commits and identify what changed.
3. For each doc file found in step 1, run

   git log -1 --format='%ci' -- <file>

   to get its last-modified date.
4. Compare each doc's last-modified date against the most recent code commit. Flag any doc older than the latest relevant code change as stale.
5. For each stale doc, run

   git diff HEAD~10 -- <file>

   and

   git diff HEAD~10 -- <related-source-dirs>

   to identify what content drifted.
6. Draft updated content for each stale doc. For README: update feature list, quickstart, and API surface. For CHANGELOG: add entries grouped by Added/Changed/Fixed/Removed. For AGENTS.md: update agent descriptions, tool lists, and capability summaries.
7. If a START-HERE document is requested, create it with: project purpose (1 paragraph), quickstart (numbered steps), architecture overview (file tree + brief annotations), active tickets or next steps, and key contacts or ownership.
8. Build a handoff checklist table: | Doc | Status | Action Taken | Reviewer Needed |.
9. Validate all internal links in updated docs by running

   grep -rn '\[.*\](.*\.md)' <doc-file>

   and checking each target exists.
10. Present the final diff of all doc changes and the handoff checklist for review.

Decision rules

• If a doc file exists but is >30 days stale relative to its source directory, mark it critical in the checklist.
• If no CHANGELOG exists and the project has >10 commits, recommend creating one.
• If AGENTS.md references agents or tools that no longer exist in the repo, remove those entries.
• Never invent features or capabilities not evidenced by the codebase — every doc claim must trace to a file or commit.
• Prefer updating existing docs over creating new ones unless a gap is clearly identified.

Output requirements

1. Doc Surface Inventory — table of all doc files with last-modified dates and staleness flags.
2. Change Summary — bullet list of what changed in the codebase since each doc was last updated.
3. Updated Doc Content — full text of each updated document (or diff if minimal changes).
4. Handoff Checklist — table with columns: Doc, Status (current/stale/missing), Action Taken, Reviewer Needed (yes/no).
5. START-HERE Document — if requested, the complete document ready to commit.

References

• references/handoff-contract.md

  — handoff structure and required sections

• references/success-criteria.md

  — what "done" looks like for doc updates
• Keep Changelog format: https://keepachangelog.com/en/1.0.0/

Related skills

• planner

  — for planning implementation work (upstream of docs)

• qa-validation

  — for verifying acceptance criteria (parallel concern)

• github-prior-art-research

  — for finding doc templates and patterns

Failure handling

• If

  git log

  is unavailable (not a git repo), fall back to file modification timestamps via

  stat

  .
• If a doc references files that no longer exist, flag the broken reference and suggest removal rather than guessing new targets.
• If the scope of changes is too large to summarize in one pass, split by directory and produce per-module doc updates.
• If the user provides no milestone context, ask for the ticket ID or date range before proceeding.