A skill that treats documentation as part of finishing a change, not an afterthought. It keeps docs, OpenAPI, configs, and comments from going stale and captures flows as Mermaid diagrams.
---
name: docs-and-diagrams
description: Use when finishing a change that affects docs, or when asked to document/diagram architecture or workflows. Triggers on 'update the docs', 'add a diagram', 'document this'.
---
Use when finishing a change that affects docs, or when asked to document/diagram architecture or workflows. Triggers on 'update the docs', 'add a diagram', 'document this'.
Guidance:
- As part of finishing work, update all docs, READMEs, OpenAPI, configs, inline comments, and architecture notes so nothing is stale.
- Add Mermaid diagrams/flowcharts for data fetching, invalidations, and dependencies.
- Put a one-command install/start at the top of the README.
- Keep helpful inline comments; remove only excess/redundant ones.
- Persist agreed conventions/decisions into AGENTS.md / memory so they apply in future sessions and other repos.Docs ship with the code#
The framing is that a change isn't done until the docs match it. Updating READMEs, OpenAPI, and comments in the same pass is what stops the slow drift into stale documentation.
Persist the decisions#
The last bullet is the multiplier: writing agreed conventions into AGENTS.md means they carry into future sessions and other repos, instead of being re-litigated every time.
What a good diagram does#
A diagram should expose a boundary, a retry path, a dependency, or a decision point. It should not decorate a README with boxes that repeat the paragraph above it.
For this site, that rule matters too. Mermaid belongs where the reader needs to see flow, ownership, or failure mode. Otherwise the stronger move is a sharper paragraph.