documentation-writing
Writing clear, discoverable software documentation following the Eight Rules and Diataxis framework. Use when creating README files, API docs, tutorials, how-to guides, or any project documentation. Automatically enforces docs/ location, linking requirements, and runnable examples.
- Installs
- 307
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/rysweet/amplihack --skill documentation-writing- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads documentation-writing automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Documentation Writing Skill
Purpose
Creates high-quality, discoverable documentation following the Eight Rules and Diataxis framework. Ensures all docs are properly located, linked, and contain real runnable examples.
When I Activate
I load automatically when you mention:
- "write documentation" or "create docs"
- "document this feature/module/API"
- "create a README" or "write a tutorial"
- "explain how this works"
- Any request to create markdown documentation
Core Rules (MANDATORY)
The Eight Rules
- Location: All docs in
docs/directory - Linking: Every doc linked from at least one other doc
- Simplicity: Plain language, remove unnecessary words
- Real Examples: Runnable code, not "foo/bar" placeholders
- Diataxis: One doc type per file (tutorial/howto/reference/explanation)
- Scanability: Descriptive headings, table of contents for long docs
- Local Links: Relative paths, context with links
- Currency: Delete outdated docs, include update metadata
What Stays OUT of Docs
Never put in docs/:
- Status reports or progress updates
- Test results or benchmarks
- Meeting notes or decisions
- Plans with dates
- Point-in-time snapshots
Where temporal info belongs:
- Test results → CI logs, GitHub Actions
- Status updates → GitHub Issues
- Progress → Pull Request descriptions
- Decisions → Commit messages
Quick Start
Creating a New Document
# [Feature Name]
Brief one-sentence description of what this is.
## Quick Start
Minimal steps to get started (3-5 steps max).
## Contents
- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)
## Configuration
Step-by-step setup with real examples.
## Usage
Common use cases with runnable code.
## Troubleshooting
Common problems and solutions.
Document Types (Diataxis)
| Type | Purpose | Location | User Question |
|---|---|---|---|
| Tutorial | Learning | docs/tutorials/ | "Teach me how" |
| How-To | Doing | docs/howto/ | "Help me do X" |
| Reference | Information | docs/reference/ | "What are the options?" |
| Explanation | Understanding | docs/concepts/ | "Why is it this way?" |
Workflow
Step 1: Determine Document Type
Ask: What is the reader trying to accomplish?
- Learning something new → Tutorial
- Solving a specific problem → How-To
- Looking up details → Reference
- Understanding concepts → Explanation
Step 2: Choose Location
docs/
├── tutorials/ # Learning-oriented
├── howto/ # Task-oriented
├── reference/ # Information-oriented
├── concepts/ # Understanding-oriented
└── index.md # Links to all docs
Step 3: Write with Examples
Every concept needs a runnable example:
# Example: Analyze file complexity
from amplihack import analyze
result = analyze("src/main.py")
print(f"Complexity: {result.score}")
# Output: Complexity: 12.5
Step 4: Link from Index
Add entry to docs/index.md:
- [New Feature Guide](./howto/new-feature.md) - How to configure X
Step 5: Validate
Checklist before completion:
- File in
docs/directory - Linked from index or parent doc
- No temporal information
- All examples tested
- Follows one Diataxis type
Navigation Guide
When to Read Supporting Files
reference.md - Read when you need:
- Complete frontmatter specification
- Detailed Diataxis type definitions
- Markdown style conventions
- Documentation review checklist
examples.md - Read when you need:
- Full document templates for each type
- Real-world documentation examples
- Before/after improvement examples
- Complex documentation patterns
Anti-Patterns to Avoid
| Anti-Pattern | Why It's Bad | Better Approach |
|---|---|---|
| "Click here" links | No context | "See auth config" |
| foo/bar examples | Not realistic | Use real project code |
| Wall of text | Hard to scan | Use headings and bullets |
| Orphan docs | Never found | Link from index |
| Status in docs | Gets stale | Use Issues/PRs |
Retcon Documentation Exception
When writing documentation BEFORE implementation (document-driven development):
# [PLANNED - Implementation Pending]
This document describes the intended behavior of Feature X.
## Planned Interface
```python
# [PLANNED] - This API will be implemented
def future_function(input: str) -> Result:
"""Process input and return result."""
pass
```
Once implemented, remove the [PLANNED] markers and update with real examples.
---
**Full reference**: See [reference.md](./reference.md) for complete specification.
**Templates**: See [examples.md](./examples.md) for copy-paste templates.
FAQ
What does the documentation-writing skill do?
Writing clear, discoverable software documentation following the Eight Rules and Diataxis framework. Use when creating README files, API docs, tutorials, how-to guides, or any project documentation. Automatically enforces docs/ location, linking requirements, and runnable examples.
How do I install documentation-writing?
Run npx skills add https://github.com/rysweet/amplihack --skill documentation-writing in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/documentation-writing/ (personal) or .claude/skills/documentation-writing/ (project).
Which AI agents can use documentation-writing?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is documentation-writing safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains documentation-writing?
It is published by rysweet in rysweet/amplihack. It has 307 recorded installs.
More from rysweet/amplihack
cybersecurity-analyst
rysweet/amplihack
Analyzes events through cybersecurity lens using threat modeling, attack surface analysis, defense-in-depth, zero-trust architecture, and risk-based frameworks (CIA triad, STRIDE, MITRE ATT&CK). Provides insights on vulnerabilities, attack vectors, defense strategies, incident response, and security posture. Use when: Security incidents, vulnerability assessments, threat analysis, security architecture, compliance. Evaluates: Confidentiality, integrity, availability, threat actors, attack patterns, controls, residual risk.
lawyer-analyst
rysweet/amplihack
Analyzes events through legal lens using statutory interpretation, case law analysis, legal reasoning, constitutional principles, and multiple legal frameworks (common law, civil law, international law). Provides insights on legal rights, obligations, liabilities, remedies, and compliance requirements. Use when: Legal disputes, contracts, regulations, compliance, rights analysis, liability assessment. Evaluates: Legal obligations, rights, liabilities, remedies, precedent, statutory authority, constitutionality.
psychologist-analyst
rysweet/amplihack
Analyzes events through psychological lens using cognitive psychology, social psychology, developmental psychology, clinical psychology, and neuroscience. Provides insights on behavior, cognition, emotion, motivation, group dynamics, decision-making biases, mental health, and individual differences. Use when: Behavioral patterns, decision-making, group behavior, mental health, leadership, persuasion, trauma, development. Evaluates: Cognitive processes, emotional responses, motivations, biases, group dynamics, personality, mental states.
mermaid-diagram-generator
rysweet/amplihack
Converts architecture descriptions, module specs, or workflow docs into Mermaid diagrams. Use when visualizing brick module relationships, workflows (DDD, investigation), or system architecture. Supports: flowcharts, sequence diagrams, class diagrams, state machines, entity relationship diagrams, and Gantt charts. Generates valid Mermaid syntax for embedding in markdown docs.
pptx
rysweet/amplihack
Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks
economist-analyst
rysweet/amplihack
Analyzes events through economic lens using supply/demand, incentive structures, market dynamics, and multiple schools of economic thought (Classical, Keynesian, Austrian, Behavioral). Provides insights on market impacts, resource allocation, policy implications, and distributional effects. Use when: Economic events, policy changes, market shifts, financial crises, regulatory decisions. Evaluates: Incentives, efficiency, opportunity costs, market failures, systemic risks.
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.