update-docs

name

update-docs

description

Repo-wide documentation sweep for updating project docs, context, ADRs, diagrams, README files, agent instructions, and documentation sites after feature work, decisions, or direction changes. Use this skill whenever the user asks to update docs, refresh documentation, prepare for PR, finish a branch, merge, ship, close out work, record what changed, or align docs with code. It first discovers the repo's key Markdown documentation and docs sites, ignores historical archives by default, presents the proposed docs plan for approval, then updates only the approved docs surgically.

Update Docs

Purpose

Run this when docs need to reflect current code, decisions, project context, or branch state. The goal is to leave future humans and agents with the current state, decisions, and next steps, without rewriting unrelated docs or repeating setup instructions that belong in README.

Use the documentation-and-adrs skill for deeper guidance when decisions, public APIs, architecture, or feature behavior changed. If that skill is available, read it before writing ADRs or decision-heavy docs.

Documentation discovery

Start by discovering the repo's documentation shape. .md, .mdx, and .html are the default file types, but include docs-site content when the repo has one.

Check these locations first when they exist:

• Docs maps or indexes: docs/docs-map.md, docs/index.md, docs/map.md, index.md, map.md.
• Agent and assistant context: AGENTS.md, CLAUDE.md.
• Project overview and commands: README.md, package or app README files when relevant.
• Changelog: CHANGELOG.md, Changelog.md, changelog.md, or repo-specific changelog files when user-visible changes need release notes.