Stats
Actions
Tags
Write software documentation that resists decay. Use this skill whenever the user wants to create, improve, or organize technical documentation — including READMEs, architecture docs, ADRs, developer guides, onboarding materials, conventions, runbooks, how-to guides, or any project docs. Trigger on phrases like 'document this repo', 'write a README', 'create an ADR', 'my docs are a mess', 'set up a docs structure', 'help me write a developer guide', or 'make our docs stop going stale'. Also trigger when asked to triage or clean up existing documentation, decide what to document at different project stages, organize docs across multiple repos, write CLAUDE.md or AI context files, or integrate documentation into PR workflows. Covers five domains (infrastructure, data, API, engineering, product) with ready-to-use templates and worked examples.
How this skill is triggered — by the user, by Claude, or both
Slash command
/project-documentation:project-documentationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Write project documentation that stays useful by matching your writing approach to each topic's shelf life.
references/examples/adr-completed.mdreferences/examples/conceptual-guide-completed.mdreferences/examples/readme-completed.mdreferences/guide-api.mdreferences/guide-data.mdreferences/guide-engineering.mdreferences/guide-infrastructure.mdreferences/guide-product.mdreferences/guide-strategy.mdreferences/guide-triage.mdreferences/guide-workflows.mdreferences/templates-long-shelf.mdreferences/templates-medium-shelf.mdreferences/templates-readme-apps.mdreferences/templates-readme-ops.mdreferences/writing-standards.mdWrite project documentation that stays useful by matching your writing approach to each topic's shelf life.
Most project documentation tries to describe the current state of the system. But current state changes constantly — every merged PR can invalidate what's written. The result: docs that are stale within weeks and that nobody trusts.
Every piece of documentation content has a shelf life — how long it'll remain accurate before the underlying reality changes. The trick is to match your approach to the shelf life of what you're writing about.
Content that rarely changes deserves full, detailed documentation. This is the highest-value writing you can do because it stays useful for months or years.
What qualifies:
Content that changes occasionally. The shape is stable but the specifics drift. Write the conceptual framing, then link to the authoritative source for current details.
What qualifies:
The pattern:
The authentication layer uses a pluggable strategy approach, making it
straightforward to add new identity providers. See `src/auth/strategies/`
for the currently supported providers and `IAuthStrategy` for the
interface contract.
Content that changes with every PR. Don't write prose about it — leave a trail of breadcrumbs pointing to where the truth lives.
What qualifies:
The pattern:
# Instead of listing every config option:
Configuration follows the schema in `config.schema.json`. Copy `.env.example`
to `.env` and adjust for your environment.
# Instead of inventorying API endpoints:
API documentation is generated from source. Run `npm run docs` or visit
`/api-docs` on a running instance.
Before writing anything, run this test:
Does this explain WHY something exists? → Write it fully (decision record)
Does this explain HOW TO THINK about something? → Write it fully (conceptual guide)
Does this establish WHAT PATTERN TO FOLLOW? → Write it fully (conventions)
Does this describe WHAT CURRENTLY EXISTS? → Breadcrumb to code/config
Does this walk through HOW TO DO A TASK? → Write the steps, breadcrumb the specifics
Use these to point without narrating:
| Don't write this | Write this instead |
|---|---|
| "The available configuration options are..." | "See config.schema.json for available options" |
| "The system currently has these services..." | "See src/services/ for the current service inventory" |
| "The API supports these endpoints..." | "See the generated API docs at /api-docs" |
| "The database tables include..." | "See migration files in src/migrations/ for the current schema" |
These signal documentation that will decay rapidly:
Good documentation reads like an operator's guide — it tells you enough to work with the system competently. Bad documentation reads like a service manual — it tries to catalog every internal detail exhaustively.
Operator's guide (write this):
Service manual (avoid this):
When reviewing a draft, ask: "Could an operator use this to work effectively in the system, without it trying to replace reading the code?" If yes, it's the right level. If it's so detailed that it competes with the source code for truth, it's a service manual and it'll rot.
Organize docs by shelf life and purpose:
/docs/
├── decisions/ # Long shelf life — why we chose what we chose
│ ├── 0001-database-choice.md
│ └── 0002-auth-strategy.md
├── guides/ # Long shelf life — how to think about the system
│ ├── architecture.md
│ ├── data-model.md
│ └── product-overview.md
├── conventions/ # Long shelf life — team agreements
│ ├── coding-standards.md
│ └── git-workflow.md
├── runbooks/ # Long shelf life — operational procedures
│ ├── dev-setup.md
│ ├── deployment.md
│ └── incident-response.md
└── how-to/ # Medium shelf life — task walkthroughs
├── add-new-service.md
└── run-migrations.md
Note the absence of a reference/ directory — prefer generated docs or direct code links for reference material.
A README is a signpost, not a textbook. Its job is four things:
Everything else belongs in /docs/.
docs/guides/docs/how-to/docs/runbooks/troubleshooting.mdFor strategic documentation decisions, consult:
These are relevant when starting a new project, inheriting a codebase, or cleaning up neglected documentation. For routine doc writing, skip to step 1.
Before writing, classify every topic using the decision flowchart above.
For domain-specific documentation, consult the appropriate reference:
Each guide specifies what to write fully, what to write-and-link, and what to breadcrumb for that domain.
Pick from the template library based on what you're writing:
For completed examples showing what finished docs look like (not just skeletons), see references/examples/.
Follow the writing standards for tone, formatting, shelf-life-aware style rules, diagram durability guidance, and a before/after rewrite gallery.
For keeping docs alive in day-to-day development:
When documenting an existing project, identify gaps:
Fill gaps using the domain guides and templates. Prioritize long-shelf-life content first — it delivers the most lasting value.
This skill draws on established ideas from the documentation community. If you want to go deeper:
npx claudepluginhub greglamb/claude-gcode-tools --plugin project-documentationEstablish documentation standards that keep docs current, discoverable, and useful. Use when scaling team or improving knowledge retention.
Guides project documentation structure, content requirements, and best practices. Includes templates for README, ARCHITECTURE, API docs, and change history.
Documentation levels and types (README, architecture, API, runbooks), keeping docs current and discoverable.