Documentation Refresh Skill
Use this skill when asked to overhaul, refresh, modernize, or clean up a
repository's documentation — especially for a system that is already in
production and has accumulated stale README content, dead analysis docs,
outdated AI-agent knowledge bases (AGENTS.md, CLAUDE.md, etc.), or
misleading code comments.
This skill is repo-agnostic. It does not assume any particular language,
framework, or doc tool. It encodes a phased process, a reusable checklist,
and a set of anti-patterns learned from running this refresh on real
production repos.
When to use this skill
- The user says something like "our docs are out of date," "refresh the
README," "clean up AGENTS.md," "audit our documentation," or "set up a
docs/ folder with architecture diagrams."
- A repo has legacy analysis files, dead feature references, or docs that
no longer match the live code.
- The user wants a repeatable framework they can reuse across repos.
How to use this skill
- Read
CHECKLIST.md in this skill directory for the phase-by-phase
process (Phase 0 through Phase 6).
- Read
ANTI-PATTERNS.md for common mistakes to avoid while auditing and
rewriting docs.
- Adapt the checklist to the target repo:
- Confirm with the user which phases apply (a small repo may not need
every phase; a large one may want each phase in its own session to
protect context windows).
- Identify the repo's actual doc tooling (Markdown + Mermaid is the
default assumption below, but adjust if the repo uses something else,
e.g. Sphinx, Docusaurus, or a wiki-only workflow).
- Always produce (or update) a running "roadmap" file in the repo root
(e.g.
DOCUMENTATION_ROADMAP.md) that captures the plan, audit
findings, and a "Lessons Learned" scratchpad. This gives future sessions
(human or agent) a clear handoff point and turns the current refresh
into reusable material for the next one.
- At natural session boundaries, write or update a
HANDOFF.md summarizing
what was done, what was verified, and exactly what the next session
should do next. Treat this as mandatory when the work will span more
than one session.
- Before declaring any phase complete, run the repo's actual lint/test
command (discover it from
AGENTS.md, README.md, justfile,
package.json, Makefile, or CI config) to make sure doc-only changes
didn't break anything, and re-check for stale references introduced by
the phase's own edits.
Core principles (apply unless the user overrides them)
- Repo docs are the source of truth. Any external wiki mirrors the
repo, never the reverse.
- Diagrams as code. Prefer Mermaid (or another text-based diagram
format already used in the repo) so diagrams stay version-controlled
and diffable.
- Separate, focused guides over one monolithic doc. Split by audience
and purpose: architecture, data flow, developer onboarding, operations,
deployment, etc.
- Delete stale docs outright rather than leaving them "for reference."
Git history is the archive.
- Update code-level docs (docstrings/comments) alongside Markdown.
A refreshed README next to a misleading docstring is a half-finished job.
- Phase the work and hand off explicitly. Long doc refreshes should be
broken into independently reviewable phases, each with its own commit(s)
and a handoff note for whoever (or whatever) picks up next.
See CHECKLIST.md for the concrete phase breakdown and ANTI-PATTERNS.md
for pitfalls to avoid.
1---2name: doc-refresh3description: Refresh a repo's documentation for a live production system — audit stale docs, rebuild a focused doc set with diagrams, update AI-agent knowledge bases, and improve code-level docstrings4metadata:5 source: https://skillmd.com/skills/robertguss/doc-refresh6---78# Documentation Refresh Skill910Use this skill when asked to overhaul, refresh, modernize, or clean up a11repository's documentation — especially for a system that is already in12production and has accumulated stale README content, dead analysis docs,13outdated AI-agent knowledge bases (`AGENTS.md`, `CLAUDE.md`, etc.), or14misleading code comments.1516This skill is repo-agnostic. It does not assume any particular language,17framework, or doc tool. It encodes a phased process, a reusable checklist,18and a set of anti-patterns learned from running this refresh on real19production repos.2021## When to use this skill2223- The user says something like "our docs are out of date," "refresh the24 README," "clean up AGENTS.md," "audit our documentation," or "set up a25 docs/ folder with architecture diagrams."26- A repo has legacy analysis files, dead feature references, or docs that27 no longer match the live code.28- The user wants a repeatable framework they can reuse across repos.2930## How to use this skill31321. Read `CHECKLIST.md` in this skill directory for the phase-by-phase33 process (Phase 0 through Phase 6).342. Read `ANTI-PATTERNS.md` for common mistakes to avoid while auditing and35 rewriting docs.363. Adapt the checklist to the target repo:37 - Confirm with the user which phases apply (a small repo may not need38 every phase; a large one may want each phase in its own session to39 protect context windows).40 - Identify the repo's actual doc tooling (Markdown + Mermaid is the41 default assumption below, but adjust if the repo uses something else,42 e.g. Sphinx, Docusaurus, or a wiki-only workflow).434. Always produce (or update) a running "roadmap" file in the repo root44 (e.g. `DOCUMENTATION_ROADMAP.md`) that captures the plan, audit45 findings, and a "Lessons Learned" scratchpad. This gives future sessions46 (human or agent) a clear handoff point and turns the current refresh47 into reusable material for the next one.485. At natural session boundaries, write or update a `HANDOFF.md` summarizing49 what was done, what was verified, and exactly what the next session50 should do next. Treat this as mandatory when the work will span more51 than one session.526. Before declaring any phase complete, run the repo's actual lint/test53 command (discover it from `AGENTS.md`, `README.md`, `justfile`,54 `package.json`, `Makefile`, or CI config) to make sure doc-only changes55 didn't break anything, and re-check for stale references introduced by56 the phase's own edits.5758## Core principles (apply unless the user overrides them)59601. **Repo docs are the source of truth.** Any external wiki mirrors the61 repo, never the reverse.622. **Diagrams as code.** Prefer Mermaid (or another text-based diagram63 format already used in the repo) so diagrams stay version-controlled64 and diffable.653. **Separate, focused guides over one monolithic doc.** Split by audience66 and purpose: architecture, data flow, developer onboarding, operations,67 deployment, etc.684. **Delete stale docs outright** rather than leaving them "for reference."69 Git history is the archive.705. **Update code-level docs (docstrings/comments) alongside Markdown.**71 A refreshed README next to a misleading docstring is a half-finished job.726. **Phase the work and hand off explicitly.** Long doc refreshes should be73 broken into independently reviewable phases, each with its own commit(s)74 and a handoff note for whoever (or whatever) picks up next.7576See `CHECKLIST.md` for the concrete phase breakdown and `ANTI-PATTERNS.md`77for pitfalls to avoid.