documenting-systems
Creates task-oriented technical documentation with progressive disclosure. Use when writing READMEs, API docs, architecture docs, or markdown documentation.
Resources
1Install
npx skillscat add rileyhilliard/claude-essentials/documenting-systems Install via the SkillsCat registry.
The skill creates task‑oriented technical documentation with progressive disclosure, arranging content into brief description, quick start, API reference, and architecture layers. It solves the issue of scattered or overly dense docs by showing only needed information up front and deeper details on demand. Use it for READMEs, API references, architecture documents, or any markdown documentation requiring clear, navigable instructions.
Technical Documentation
For writing style, tone, and voice guidance, use Skill(ce:writer) with The Engineer persona.
Core Principles
1. Progressive Disclosure
Reveal information in layers:
| Layer | Content | User Question |
|---|---|---|
| 1 | One-sentence description | What is it? |
| 2 | Quick start code block | How do I use it? |
| 3 | Full API reference | What are my options? |
| 4 | Architecture deep dive | How does it work? |
Warnings, breaking changes, and prerequisites go at the TOP.
2. Task-Oriented Writing
<!-- Bad: Feature-oriented -->
## AuthService Class
The AuthService class provides authentication methods...
<!-- Good: Task-oriented -->
## Authenticating Users
To authenticate a user, call login() with credentials:3. Show, Don't Tell
Every concept needs a concrete example.
Formatting Standards
- Sentence case headings: "Getting started" not "Getting Started"
- Max 3 heading levels: Deeper means split the doc
- Always specify language in code blocks
- Relative paths for internal links
- Tables for structured data with 3+ attributes
Quality Checklist
- Code examples tested and runnable
- No placeholder text or TODOs
- Matches actual code behavior
- Scannable without reading everything
- Reader knows what to do next
Anti-Patterns
| Problem | Fix |
|---|---|
| Wall of text | Break up with headings, bullets, code, tables |
| Buried critical info | Warnings/breaking changes at TOP |
| Missing error docs | Always document what can go wrong |
Templates
For README, API endpoint, and file organization templates, see references/templates.md.
Related Skills
Skill(ce:writer)- Writing style, tone, and voice (load The Engineer persona)Skill(ce:visualizing-with-mermaid)- Architecture and flow diagrams
Categories
Install
npx skillscat add rileyhilliard/claude-essentials/documenting-systems Install via the SkillsCat registry.