メニュー
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.
| name | documentation-writing |
| version | 1.0.0 |
| description | 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. |
| source_urls | ["https://diataxis.fr/","https://www.writethedocs.org/guide/writing/docs-principles/","https://github.blog/developer-skills/documentation-done-right-a-developers-guide/"] |
| auto_activates | ["write documentation","create docs","document this feature","create a README","write a tutorial","api docs","how-to guide"] |
| token_budget | 1800 |
Creates high-quality, discoverable documentation following the Eight Rules and Diataxis framework. Ensures all docs are properly located, linked, and contain real runnable examples.
I load automatically when you mention:
docs/ directoryNever put in docs/:
Where temporal info belongs:
# [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.
| 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?" |
Ask: What is the reader trying to accomplish?
docs/
├── tutorials/ # Learning-oriented
├── howto/ # Task-oriented
├── reference/ # Information-oriented
├── concepts/ # Understanding-oriented
└── index.md # Links to all docs
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
Add entry to docs/index.md:
- [New Feature Guide](./howto/new-feature.md) - How to configure X
Checklist before completion:
docs/ directoryreference.md - Read when you need:
examples.md - Read when you need:
| 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 |
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.
Systematic 4-phase debugging with root cause investigation. Use when fixing bugs to prevent random fixes.
Generate and iterate images in Cursor using the built-in image model and strong prompts. Use when creating icons, illustrations, UI mockups, diagrams, marketing visuals, or any raster asset from a text description or reference image.
Search and navigate large codebases efficiently. Use when finding specific code patterns, tracing function calls, understanding code structure, or locating bugs. Handles semantic search, grep patterns, AST analysis.
Apply appropriate design patterns (Singleton, Factory, Observer, Strategy, etc.) to solve architectural problems. Use when refactoring code architecture, implementing extensible systems, or following SOLID principles.
Technical documentation expert for creating clear, comprehensive documentation. Use when user asks to write docs, create README, or document code.
Build modern React/Next.js frontends. Use when creating web applications, choosing frontend stack, structuring components, or implementing UI/UX designs. Covers React, Next.js, Tailwind CSS, and component patterns.