Documentation
Technical writing, diagram-as-code, and documentation lifecycle management. Treats docs as code: version-controlled, linted, and CI-verified.
When to use: Creating or updating technical documentation, generating Mermaid diagrams (flowcharts, ERDs, sequence diagrams), auditing documentation coverage against code, or establishing style guides.
When NOT to use: Writing marketing copy, blog posts, or content that does not live alongside code.
Quick Reference
| Task |
Approach |
Key Point |
| Doc sync audit |
git diff main...HEAD + export scan |
Compare symbols against doc coverage |
| Sequence diagram |
Mermaid sequenceDiagram + autonumber |
Map messages to function calls |
| ERD |
Mermaid erDiagram + Crow's Foot |
Derive from Drizzle/Prisma schemas |
| Gitgraph |
Mermaid gitGraph |
Standardize on main/develop/feature branches |
| Feature release doc |
Overview + Config + Examples + Troubleshooting |
Checklist for every new feature |
| API reference |
Generate from JSDoc/TSDoc annotations |
Never write API refs manually |
| Style guide |
Active voice + present tense + direct address |
Conversational but precise |
| AI-assisted drafting |
Inventory + gap analysis + draft + human review |
AI drafts, humans verify accuracy |
| Markdown standard |
YAML frontmatter + language-tagged code blocks |
Always specify code block language |
| Complex diagrams |
Split into focused sub-diagrams + subgraphs |
Limit to 15-20 nodes per diagram |
Common Mistakes
| Mistake |
Correct Pattern |
| Using static images for technical diagrams |
Write Mermaid syntax inline in Markdown |
Generic participant names like Agent1 |
Use specific service or role names matching the architecture |
| Manually writing API reference docs |
Generate from JSDoc/TSDoc annotations in source code |
| Diagrams with 20+ nodes and no grouping |
Use subgraphs to group related nodes; limit to 15-20 |
| Documentation referencing outdated defaults |
Run doc sync audit comparing exports against coverage |
| Using "Click here" link text |
Use descriptive anchor text for accessibility and clarity |
| Skipping heading hierarchy levels |
Never go from H2 to H4; keep hierarchy sequential |
| Mixing wall-of-text paragraphs |
Use bullet points, tables, and diagrams for scannability |
Delegation
- Scan codebase for undocumented exports and documentation gaps: Use
Explore agent
- Generate a full documentation site with diagrams from an existing codebase: Use
Task agent
- Plan documentation architecture and information hierarchy for a new project: Use
Plan agent
If the mermaid-diagrams skill is available, delegate complex diagram creation and advanced Mermaid syntax questions to it.
Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s mermaid-diagrams -a claude-code -y
References
- Writing Style -- Voice, tone, formatting rules, error message guidelines, and structural standards
- Mermaid Diagrams -- Sequence, ERD, gitgraph, flowchart patterns with anti-patterns and troubleshooting
- Doc Coverage -- Feature inventory, gap analysis, code-first and doc-first audit workflows
- AI Collaboration -- AI-human doc workflow, hallucination handling, documentation-as-code practices
- Markdown Standards -- Frontmatter, headings, code blocks, tables, callouts, and link conventions
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: technical-docs3description: Technical documentation writing and diagram generation. Use when creating docs, syncing documentation with code changes, building Mermaid diagrams, running doc coverage audits, or establishing writing style guides. Use for doc-as-code workflows, ERD generation, sequence diagrams, documentation gap analysis, and AI-assisted drafting. Use when this capability is needed.4---56# Documentation78Technical writing, diagram-as-code, and documentation lifecycle management. Treats docs as code: version-controlled, linted, and CI-verified.910**When to use**: Creating or updating technical documentation, generating Mermaid diagrams (flowcharts, ERDs, sequence diagrams), auditing documentation coverage against code, or establishing style guides.1112**When NOT to use**: Writing marketing copy, blog posts, or content that does not live alongside code.1314## Quick Reference1516| Task | Approach | Key Point |17| -------------------- | ----------------------------------------------- | -------------------------------------------- |18| Doc sync audit | `git diff main...HEAD` + export scan | Compare symbols against doc coverage |19| Sequence diagram | Mermaid `sequenceDiagram` + `autonumber` | Map messages to function calls |20| ERD | Mermaid `erDiagram` + Crow's Foot | Derive from Drizzle/Prisma schemas |21| Gitgraph | Mermaid `gitGraph` | Standardize on main/develop/feature branches |22| Feature release doc | Overview + Config + Examples + Troubleshooting | Checklist for every new feature |23| API reference | Generate from JSDoc/TSDoc annotations | Never write API refs manually |24| Style guide | Active voice + present tense + direct address | Conversational but precise |25| AI-assisted drafting | Inventory + gap analysis + draft + human review | AI drafts, humans verify accuracy |26| Markdown standard | YAML frontmatter + language-tagged code blocks | Always specify code block language |27| Complex diagrams | Split into focused sub-diagrams + subgraphs | Limit to 15-20 nodes per diagram |2829## Common Mistakes3031| Mistake | Correct Pattern |32| ------------------------------------------- | ------------------------------------------------------------ |33| Using static images for technical diagrams | Write Mermaid syntax inline in Markdown |34| Generic participant names like `Agent1` | Use specific service or role names matching the architecture |35| Manually writing API reference docs | Generate from JSDoc/TSDoc annotations in source code |36| Diagrams with 20+ nodes and no grouping | Use subgraphs to group related nodes; limit to 15-20 |37| Documentation referencing outdated defaults | Run doc sync audit comparing exports against coverage |38| Using "Click here" link text | Use descriptive anchor text for accessibility and clarity |39| Skipping heading hierarchy levels | Never go from H2 to H4; keep hierarchy sequential |40| Mixing wall-of-text paragraphs | Use bullet points, tables, and diagrams for scannability |4142## Delegation4344- **Scan codebase for undocumented exports and documentation gaps**: Use `Explore` agent45- **Generate a full documentation site with diagrams from an existing codebase**: Use `Task` agent46- **Plan documentation architecture and information hierarchy for a new project**: Use `Plan` agent4748> If the `mermaid-diagrams` skill is available, delegate complex diagram creation and advanced Mermaid syntax questions to it.49> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s mermaid-diagrams -a claude-code -y`5051## References5253- [Writing Style](references/writing-style.md) -- Voice, tone, formatting rules, error message guidelines, and structural standards54- [Mermaid Diagrams](references/mermaid-diagrams.md) -- Sequence, ERD, gitgraph, flowchart patterns with anti-patterns and troubleshooting55- [Doc Coverage](references/doc-coverage.md) -- Feature inventory, gap analysis, code-first and doc-first audit workflows56- [AI Collaboration](references/ai-collaboration.md) -- AI-human doc workflow, hallucination handling, documentation-as-code practices57- [Markdown Standards](references/markdown-standards.md) -- Frontmatter, headings, code blocks, tables, callouts, and link conventions5859---60> Converted and distributed by [TomeVault](https://tomevault.io/claim/jbabin91) — claim your Tome and manage your conversions.61<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io