CO
common-documentation
Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.
Install
mkdir -p .claude/skills/common-documentation && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/16015" && unzip -o skill.zip -d .claude/skills/common-documentation && rm skill.zipInstalls to .claude/skills/common-documentation
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.197 chars✓ has a “when” trigger
About this skill
Documentation Standards
Priority: P2 (MAINTENANCE)
1. Intent-First Comments
- Explain "Why" logic exists. Avoid "What" mechanics.
- Use triple-slash (Dart/Swift) or JSDoc (TS/JS) for public members.
- Delete commented-out code. Use Git history.
- Format:
TODO(username): description. Link tickets.
2. README Structure
- Mission: Project purpose (one sentence).
- Onboarding: Prerequisites, installation, usage (exact).
- Maintenance: Document inputs/outputs, known quirks, fixes.
- Sync: Documentation ships with feature.
3. ADRs & Architecture
- ADRs: Document rationale for system changes in
docs/adr/. - Docstrings: Include Args, Returns, and Usage examples (
>>>). - Diagrams: Use Mermaid.js inside Markdown.
4. API Docs
- Use Swagger/OpenAPI for REST.
- Provide copy-pasteable examples for endpoints.
- Define contract before implementation.
Anti-Patterns
- No "what" comments: Explain intent. Refactor mechanics.
- No orphan TODOs: Require owner and ticket.
- No stale docs: Document during development.