Documentation Standards Skill
Overview
Standards and requirements for project documentation. Defines required files, format standards, content guidelines, and automated documentation triggers.
Type
standards
When to Invoke
Trigger keywords: documentation, docs, readme, API reference, changelog, roadmap, schemas, data flow
Invoke when:
- Starting a new project
- Reviewing documentation completeness
- Before commits (doc check)
- After significant code changes
- Creating API documentation
Required ./docs/ Files
Every project should have:
| File |
Purpose |
ROADMAP.md |
Overview, features, architecture, future plans |
API_REFERENCE.md |
Endpoints, schemas, examples |
DATA_FLOW.md |
Architecture, patterns, data interactions |
SCHEMAS.md |
Database schemas, models, validation rules |
BUG_REFERENCE.md |
Known issues, causes, solutions, prevention |
VERSION_LOG.md |
Release history, changes by version |
memory-archive/ |
Historical CLAUDE.md versions (via /prune) |
Format & Style Standards
Headers
- Use ##/### hierarchically
- Don't skip levels (## then ####)
Metadata
- Include "Last Updated" date
- Include version number where relevant
Line Length
- Maximum 100 characters per line
- Break long lines for readability
Code Blocks
- Always specify language
- Include runnable examples where possible
Examples
- Provide practical, copy-paste examples
- Show both input and expected output
Content Guidelines
- Write for future developers - Assume no context
- Explain "why" not just "what" - Rationale matters
- Cross-link related docs - Connect concepts
- Stay focused on topic - One doc, one purpose
- Version significant changes - Track evolution
Automated Documentation Triggers
| Event |
Action |
| Bug fix |
Update BUG_REFERENCE.md (description, cause, solution, prevention) |
| New feature |
Update ROADMAP.md (description, architecture, APIs) |
| API change |
Update API_REFERENCE.md (endpoints, breaking changes, migration) |
| Architecture change |
Update DATA_FLOW.md |
| Database change |
Update SCHEMAS.md |
| Before commit |
Check all docs for accuracy |
/changes command |
Update VERSION_LOG.md |
/prune command |
Archive to memory-archive/ |
/changes Checklist
Before running /changes:
Documentation Review Questions
When reviewing docs, ask:
- Could a new developer understand this?
- Are there undocumented APIs or features?
- Are examples current and working?
- Are there broken cross-references?
- Is the version history accurate?
Template: New Documentation File
# [Title]
*Last Updated: YYYY-MM-DD | Version: X.Y.Z*
## Overview
Brief description of what this document covers.
## [Main Sections]
Content organized hierarchically.
## Examples
Practical examples with code blocks.
## Related Documentation
- [[Link to related doc]]
- [[Another related doc]]
---
*Maintained by: [owner]*
Integration
Works with:
/changes command - Updates VERSION_LOG/prune command - Archives to memory-archive/systematic-debugging skill - BUG_REFERENCE updates
1---2name: documentation-standards3description: Technical documentation standards for APIs, architecture, and developer guides4---56# Documentation Standards Skill78## Overview910Standards and requirements for project documentation. Defines required files, format standards, content guidelines, and automated documentation triggers.1112## Type1314standards1516## When to Invoke1718**Trigger keywords:** documentation, docs, readme, API reference, changelog, roadmap, schemas, data flow1920**Invoke when:**21- Starting a new project22- Reviewing documentation completeness23- Before commits (doc check)24- After significant code changes25- Creating API documentation2627## Required `./docs/` Files2829Every project should have:3031| File | Purpose |32|------|---------|33| `ROADMAP.md` | Overview, features, architecture, future plans |34| `API_REFERENCE.md` | Endpoints, schemas, examples |35| `DATA_FLOW.md` | Architecture, patterns, data interactions |36| `SCHEMAS.md` | Database schemas, models, validation rules |37| `BUG_REFERENCE.md` | Known issues, causes, solutions, prevention |38| `VERSION_LOG.md` | Release history, changes by version |39| `memory-archive/` | Historical CLAUDE.md versions (via /prune) |4041## Format & Style Standards4243### Headers44- Use ##/### hierarchically45- Don't skip levels (## then ####)4647### Metadata48- Include "Last Updated" date49- Include version number where relevant5051### Line Length52- Maximum 100 characters per line53- Break long lines for readability5455### Code Blocks56- Always specify language57- Include runnable examples where possible5859### Examples60- Provide practical, copy-paste examples61- Show both input and expected output6263## Content Guidelines64651. **Write for future developers** - Assume no context662. **Explain "why" not just "what"** - Rationale matters673. **Cross-link related docs** - Connect concepts684. **Stay focused on topic** - One doc, one purpose695. **Version significant changes** - Track evolution7071## Automated Documentation Triggers7273| Event | Action |74|-------|--------|75| Bug fix | Update BUG_REFERENCE.md (description, cause, solution, prevention) |76| New feature | Update ROADMAP.md (description, architecture, APIs) |77| API change | Update API_REFERENCE.md (endpoints, breaking changes, migration) |78| Architecture change | Update DATA_FLOW.md |79| Database change | Update SCHEMAS.md |80| Before commit | Check all docs for accuracy |81| `/changes` command | Update VERSION_LOG.md |82| `/prune` command | Archive to memory-archive/ |8384## `/changes` Checklist8586Before running `/changes`:87- [ ] APIs documented in API_REFERENCE88- [ ] Bugs documented in BUG_REFERENCE89- [ ] Features documented in ROADMAP90- [ ] VERSION_LOG entry prepared91- [ ] Cross-references valid92- [ ] Examples still work9394## Documentation Review Questions9596When reviewing docs, ask:971. Could a new developer understand this?982. Are there undocumented APIs or features?993. Are examples current and working?1004. Are there broken cross-references?1015. Is the version history accurate?102103## Template: New Documentation File104105```markdown106# [Title]107108*Last Updated: YYYY-MM-DD | Version: X.Y.Z*109110## Overview111112Brief description of what this document covers.113114## [Main Sections]115116Content organized hierarchically.117118## Examples119120Practical examples with code blocks.121122## Related Documentation123124- [[Link to related doc]]125- [[Another related doc]]126127---128*Maintained by: [owner]*129```130131## Integration132133Works with:134- `/changes` command - Updates VERSION_LOG135- `/prune` command - Archives to memory-archive/136- `systematic-debugging` skill - BUG_REFERENCE updates
SubashMuruganDev