| name | documentation |
| description | Writing quality guidelines, formatting conventions, and styling constraints for documentation.
Trigger when:
- Writing, editing, or auditing documentation files, READMEs, markdown files, or guides.
- Modifying files with suffixes like: *.md, *.qmd, *.txt, *.rst.
- Prompt contains keywords: doc, documentation, spelling, grammar, headers, links, table alignment, Divio, tone, voice, clarity.
|
Documentation
This skill governs how you write. Section 1 applies to all text you produce — code comments, chat responses, documentation. (Commit messages are governed by commit-hygiene, which owns that jurisdiction in the §5 routing table.) Section 2 applies when you are producing or editing a standalone document (README, guide, reference page, explanation, specification).
Section 1: Core Writing Principles
These rules are always active. They are non-negotiable.
1. Answer First
Lead with the conclusion, not the context. The reader's question should be answered in the first sentence or heading — background, caveats, and methodology come after. If someone stops reading after one paragraph, they should still have the answer.
2. Active Voice
Default to active voice. Use passive only when the actor is genuinely irrelevant or unknown. "The function returns an error" — not "An error is returned by the function."
3. Sentence Economy
One idea per sentence. Delete words that don't earn their place. If a sentence works without a word, remove that word. Prefer concrete language over abstract hedging.
4. Terminology Lock
Once you name a concept, use that name everywhere. Do not swap synonyms for variety — consistency beats prose elegance. If the codebase calls it a "store," never call it a "repository" or "database" in documentation. Terminological inconsistency is a documentation bug.
5. Scannable Structure
Readers scan before they read. Support this:
- Use meaningful headings (not "Overview" or "Introduction" — say what the section contains)
- Use bullet points for lists of 3+
- Bold key terms on first use
- Front-load important words in headings and list items
6. No Filler
Do not pad text with words that add no information.
[!CAUTION]
Anti-Patterns (FORBIDDEN):
- ❌ Preamble walls: "In this section, we will discuss the various aspects of..."
- ❌ Restating the question: "You asked about X. X is an important topic. Let me explain X."
- ❌ Hedge-word padding: "It's worth noting that perhaps it might be considered..."
- ❌ Empty transitions: "Now let's move on to the next topic."
- ❌ Compliment-before-content: "Great question! That's a really interesting point."
- ❌ Metatext about your own process: "I'll analyze this step by step."
✅ Correct behavior: Start with the substance. If a paragraph's first sentence could be deleted without losing information, delete it.
Section 2: Documentation Production
Activation scope: Apply this section when producing or editing a standalone document — any file whose primary purpose is to communicate information to a reader (README, guide, reference, spec, tutorial, explanation). Code comments are governed by Section 1. Commit messages defer to commit-hygiene.
7. Document Classification (Divio Model)
Before drafting, identify which type of document you are writing. Each type has a distinct purpose, tone, and structure — mixing them produces documents that serve no audience well.
| Type | Purpose | Tone | Structure |
|---|
| Tutorial | Learning by doing | Guiding, encouraging | Step-by-step, linear, no forks |
| How-To | Solve a problem | Practical, direct | Numbered steps to a result |
| Reference | Describe the machine | Austere, precise | Tables, lists, type signatures |
| Explanation | Build understanding | Discursive, honest | Prose, diagrams, "why" chains |
A document should be one type. If you need to explain and provide reference, write two documents (or two clearly separated sections). A tutorial that drifts into reference material fails at both.
8. Audience Declaration
State who the reader is, either explicitly ("This guide is for developers integrating the X API") or implicitly through level of assumed knowledge. Do not write for everyone — writing for everyone serves no one. Key dimensions:
- Domain familiarity — do they know the problem space?
- Tool familiarity — have they used this software before?
- Goal — learning, reference-checking, or troubleshooting?
9. Self-Consistency
A document must not contradict itself. Before finalizing:
- Verify terminology is consistent throughout (see Terminology Lock, §4)
- Check that claims in the introduction match the body
- Confirm cross-references point to content that exists and says what you claim it says
10. Scope Economy
Write the minimum documentation that eliminates the maximum confusion. Every sentence must address the reader's information need, not the general topic. Ask: "If I remove this paragraph, does the reader lose something they need?" If not, remove it.
[!IMPORTANT]
Over-documentation is itself a maintenance burden. Stale, verbose docs are worse than concise, current ones. Prefer a short document you will maintain over a comprehensive one you won't.
11. Progressive Disclosure
Present the simple, common path first. Link to edge cases, advanced configuration, and error recovery rather than interleaving them with the main flow. The reader who needs exceptions will follow the link; the reader who doesn't will thank you for not burying them.
12. Documentation Debt
Documentation debt is a first-class concept, parallel to technical debt:
- Missing docs — a feature exists but has no documentation
- Stale docs — documentation describes a previous version of the code
- Misleading docs — documentation is factually wrong or implies incorrect usage
- Orphaned docs — documentation references concepts, files, or APIs that no longer exist
When you encounter documentation debt, flag it explicitly. Do not silently work around it.
13. Markdown Audit: Links, Headers, and Linting
When editing or auditing markdown files, enforce the following structural rules. They keep documents portable across host environments and consistent in formatting.
Link integrity and portability — all markdown file cross-references must resolve from any host environment or mounting context:
- Use standard Markdown link format: All links must follow
[text](url).
- Use relative paths: Link between files using relative markdown paths (e.g.
[constitution](../constitution/SKILL.md)).
- Forbid machine-specific absolute paths: Never use absolute file URIs (e.g.,
file:///var/home/... or file:///absolute/path/...) in any documentation, comments, or plans. They are host-specific and fail to resolve when skills or projects are copied, symlinked, or cloned.
- Verify: Proactively audit link targets to confirm that the relative references resolve correctly from the directory of the file containing the link.
Header hierarchy — use a single <h1> (one #) per page, then nest header levels sequentially (##, ###, ...) without skipping a level.
Linting standards:
- Align table columns.
- Use a consistent list symbol (
-).
- Leave no trailing spaces.
To check link integrity automatically, run the script at doc-audit/scripts/check_docs.py: it scans markdown files for broken local and external links.
