update-docs · alexj11324 — Claude Code skill: docs updates and install
update-docs is a Claude Code skill that finds project docs affected by code or decision changes. It proposes edits first and waits for approval.
MIT ★ 88 updated 2026-11-17
npx skills add alexj11324/Mikka --skill update-docs -a claude-codeWhat update-docs does
update-docs scans a repository for key Markdown files and documentation-site content, then edits only the documents approved in its plan. It can run after feature work or decisions, and when a branch is being prepared for a PR, merged, or shipped.
It checks project guides, agent instructions, changelogs, ADRs, diagrams, plans, and roadmaps. Archived and completed sections are skipped by default. No files change before the plan is approved.
What it helps with
- refresh a README after changing setup or run commands
- bring ADRs and diagrams in line with a decision
- prepare project docs for a PR or release
- revise agent instructions after a change in project direction
Example prompts for the agent
- Update the docs affected by this branch and show me the proposed edits first.
- Prepare the documentation for a PR; check the README, changelog, and agent instructions.
- Record this architecture decision in an ADR and update the related docs.
How to install update-docs
1Skills CLI (Vercel)
npx skills add alexj11324/Mikka --skill update-docs -a claude-code2Manually: put the files in place
~/.claude/skills/update-docs/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/update-docs/
1Skills CLI (Vercel)
npx skills add alexj11324/Mikka --skill update-docs -a codex2Manually: put the files in place
.agents/skills/update-docs/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add alexj11324/Mikka --skill update-docs -a cursor2Manually: put the files in place
.cursor/skills/update-docs/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install alexj11324/Mikka .claude/skills/update-docs2Manually: put the files in place
.github/skills/update-docs/SKILL.md1Skills CLI (Vercel)
npx skills add alexj11324/Mikka --skill update-docs -a gemini-cli2Platform CLI
gemini skills install https://github.com/alexj11324/Mikka --path .claude/skills/update-docsManually: put the files in place
.devin/skills/update-docs/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about update-docs
How do I install update-docs in Claude Code?
Run npx skills add alexj11324/Mikka --skill update-docs -a claude-code. The skill file is available at ~/.claude/skills/update-docs/SKILL.md.
What does update-docs do?
It finds project documentation affected by code or decision changes, then presents a proposed edit plan. Only approved files are changed.
When does update-docs update project docs?
It responds to requests to refresh documentation, prepare a PR, finish a branch, or align docs with code. Archived and completed sections are skipped by default.
Source text
SKILL.md · MIT
--- 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. - Project context: `CONTEXT.md`, `docs/CONTEXT.md`. - ADRs: `docs/adr/`. - Diagrams: `docs/diagrams/`. - Documentation sites: `apps/online-docs/`, Mintlify docs directories, or similar docs-app content. - Specs, plans, roadmaps, and milestone docs under `docs/`. Useful discovery commands: ```bash find . -path '*/_archive/*' -prune -o -path '*/_done/*' -prune -o -type f \( -name '*.md' -o -name '*.mdx' \) -print find . -maxdepth 4 -type f \( -name 'docs-map.md' -o -name 'index.md' -o -name 'map.md' -o -name 'AGENTS.md' -o -name 'CLAUDE.md' -o -name 'README.md' -o -name 'CHANGELOG.md' -o -name 'Changelog.md' -o -name 'changelog.md' -o -name 'CONTEXT.md' \) -print find apps/online-docs -type f \( -name '*.md' -o -name '*.mdx' \) -print 2>/dev/null ``` Ignore historical artifacts by default unless the user explicitly asks to update them: - `_archive/*` and nested `*/_archive/*`. - `_done/*` and nested `*/_done/*`. - Generated build output, vendored dependencies, and package-manager directories. After discovery, present the docs plan and wait for user approval before editing. Include: - Docs proposed for update, with the reason each may need an edit. - Docs reviewed but likely left unchanged. - Docs intentionally ignored, including archives and done folders. - Any uncertainty about source-of-truth docs or conflicting docs. ## Workflow 1. Inspect the branch state. ```bash git status --short --branch git diff --stat main...HEAD 2>/dev/null || git diff --stat git diff --name-status main...HEAD 2>/dev/null || git diff --name-status ``` 2. Identify what changed. Look for: - Product behavior changes. - Architecture or dependency decisions. - Public API, IPC, preload, transport, storage, or data-shape changes. - Milestone, spike, or plan status changes. - New gotchas future agents should know. - Commands or setup changes that belong in README. - Diagrams that no longer match the code or decision. - Prototype code or dependencies that should not survive a no-go spike. 3. Decide which docs need edits. Use this routing: - `README.md`: setup, run, test, release, troubleshooting commands. - `CHANGELOG.md`, `Changelog.md`, `changelog.md`, or equivalent: user-visible changes, release notes, migration notes, breaking changes when the repo maintains a changelog. - `AGENTS.md` and `CLAUDE.md`: durable project context, current direction, repo map, agent-relevant rules. - `CONTEXT.md`: domain language, product context, current architecture, project constraints. - Docs maps and indexes: navigation, source-of-truth pointers, status summaries. - `docs/adr/`: accepted or rejected architectural decisions, dependency decisions, expensive-to-reverse choices. - `docs/diagrams/`: system flows, architecture diagrams, state/session diagrams. - `apps/online-docs/` and similar docs sites: public or internal user-facing documentation, Mintlify pages, navigation metadata. - Specs, plans, roadmaps, and milestone docs under `docs/`: specs, spike outcomes, roadmap status, milestone scope. 4. Present the docs plan for approval. Do not edit documentation until the user approves the proposed list. Use this concise format: ```markdown Proposed docs updates: - `path`: why it should change Likely unchanged: - `path`: why no edit seems needed Ignored by default: - `path`: historical/generated/vendor reason Questions: - [Only include blockers or source-of-truth uncertainty] ``` 5. Update approved docs surgically. - Record why a decision was made, not just what changed. - Keep roadmap status aligned with ADRs and spike specs. - Link related docs instead of duplicating long explanations. - Keep README as the home for commands. Do not repeat command lists in AGENTS.md or specs. - Remove stale open questions when the question has been answered. - Preserve spike outcomes in specs or ADRs. Do not keep dead prototype code or dependencies unless explicitly adopted. - Do not rewrite unrelated prose or reformat whole files. 6. ADR guidance. Write or update an ADR when the branch includes: - A selected or rejected library/framework. - A session, storage, IPC, transport, auth, or data-model decision. - A durable workflow or milestone direction change. - A no-go spike result that affects future implementation. Use this concise ADR shape: ```markdown # ADR 000N: [Decision title] ## Status Accepted ## Context [Why this decision came up, constraints, and relevant alternatives.] ## Decision [The choice in direct language.] ## Consequences - [Impact on implementation.] - [Future revisit trigger, if any.] ``` 7. Verify docs. For docs-only changes, run targeted checks: ```bash git diff --check rg -n "TBD|TODO|broken-link-placeholder" AGENTS.md CLAUDE.md README.md CHANGELOG.md Changelog.md changelog.md CONTEXT.md docs apps/online-docs 2>/dev/null || true ``` Also verify referenced files exist: ```bash for f in <paths-you-linked>; do test -e "$f" || echo "missing: $f"; done ``` For code plus docs changes, also run the smallest deterministic code checks that prove the changed behavior. Prefer the repo `check` command for final verification when practical. 8. Report the result. Use this concise format: ```markdown Docs updated: - `path`: what changed Decision records: - `path`: decision captured, or "none needed" Verification: - `command`: result ``` ## Stop and ask Ask before proceeding when: - The branch has competing possible decisions and the user has not chosen one. - A stale doc conflicts with code and you cannot tell which is authoritative. - The discovered docs plan has not been approved yet. - Updating docs would require inventing roadmap scope or acceptance criteria. - The only evidence for a claim is a prototype that the user wants discarded. ## Common misses - Updating a spike spec but not the roadmap. - Recording a decision in prose but not an ADR. - Leaving an answered question in Open Questions. - Keeping no-go prototype dependencies in `package.json`. - Adding setup commands to AGENTS.md instead of README. - Forgetting diagrams after changing architecture or data flow.
© alexj11324 · MIT · alexj11324/Mikka
Similar skills
All skills for Writing and docs →update-docs by other authors comes first.