writing-documentation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: writing-documentation
description: Write clear, effective technical documentation following industry-proven patterns from exemplary projects and authoritative style guides, with built-in countermeasures for common LLM documentation issues
---

# Writing Documentation Skill

## Variables

### Commands

- `CLAUDE_PRINT_COMMAND`: `claude --print --model haiku`

### Agents

- `RESEARCHER_AGENT`: `researcher`
- `DOCS_REVIEWER_AGENT`: `docs-reviewer`

## Documentation Types (Diátaxis Framework)

- **Tutorial** - Learning-oriented, step-by-step
- **How-to** - Task-oriented, specific problems
- **Reference** - Technical specifications
- **Explanation** - Clarifies concepts

Details in `references/best-practices.md`.

## Writing for Claude Code

**CRITICAL**: When writing documentation that Claude reads (SKILL.md, CLAUDE.md, commands, agents):

### 1. Test Claude's Base Knowledge First

Verify what Claude already knows:

```bash
# Use haiku for cost-effective testing (gives same quality answers as sonnet)
$CLAUDE_PRINT_COMMAND "Do NOT use any skills. How would you [perform task]?"
$CLAUDE_PRINT_COMMAND "Do NOT use any skills. When should you [make decision]?"
```

### 2. Document ONLY Unique Patterns

Include only what Claude wouldn't naturally do:

- ✓ Opinionated architectural choices
- ✓ Counter-intuitive decisions
- ✓ Project-specific conventions
- ✓ Non-default patterns

Remove redundant content:
- ✗ Standard library usage
- ✗ Common best practices
- ✗ Well-known patterns
- ✗ Basic language features

### 3. Example: React Skill Reduction

Testing revealed Claude knows TanStack Query/Zustand/RTL patterns but doesn't default to:
- "Test stores, not components" (counter-cultural)
- "NO useState for complex logic" (prescriptive)
- "Inline actions unless repeated 2+" (specific rule)

Result: 328→125 lines (-62%) by documenting only unique opinions.

## Verifying Technical Accuracy

### API Verification Workflow

When documenting unfamiliar APIs or libraries:

**1. Launch `$RESEARCHER_AGENT`:**

```
Use Task tool to launch `$RESEARCHER_AGENT` agent to verify [API/library] documentation
```

`$RESEARCHER_AGENT` uses Context7 MCP to fetch official API docs and verify method signatures.

**2. Read the codebase:**

For internal/project APIs:

```
Read relevant source files to verify method signatures exist
```

**3. State version requirements:**
- Specify versions when certain: `# Using pandas 2.0+ DataFrame.merge()`
- Add verification note when uncertain: `# Verify this API exists in your version`

**4. Direct to official docs:**
Add link to authoritative source.

### Security Verification

**Required checks before documenting code:**

1. **SQL**: Parameterized queries, never string concatenation
2. **YAML**: `yaml.safe_load()`, never `yaml.load()`
3. **Credentials**: Environment variables, never hard-coded
4. **Input**: Always validate before processing
5. **Errors**: Handle network/file operations

Use `$RESEARCHER_AGENT` agent if uncertain about security best practices.

## Code Example Requirements

### Every Example Must Include

1. **All imports and dependencies**
2. **Complete, copy-paste ready code** (no ellipsis or pseudo-code)
3. **Expected output** when relevant
4. **Error handling** for production use
5. **Context explaining "why"**

Example:

```python
# Process in batches of 1000 to avoid memory exhaustion.
# Testing: smaller (100) = 3x overhead, larger (10000) = OOM on 8GB systems.
BATCH_SIZE = 1000

for batch in chunks(items, BATCH_SIZE):
    process_batch(batch)
```

### Production-Ready Requirements

Include when relevant:
- Authentication/authorization
- Logging for debugging
- Rate limiting and retries
- Timeout handling
- Resource cleanup

See `references/best-practices.md` for complete production-ready examples.

## Using `$DOCS_REVIEWER_AGENT`

After writing documentation:

```
Use `$DOCS_REVIEWER_AGENT` agent to ruthlessly simplify
```

The agent challenges every element's necessity, asking "Would the docu