Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/nilecui/skillsbase --skill documentation-writingAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
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 docsStep 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.5Step 4: Link from Index
Add entry to docs/index.md:
- [New Feature Guide](./howto/new-feature.md) - How to configure XStep 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
[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.



