---
name: documentation
description: Use this skill whenever writing any document - plans, proposals, docs, documentation, brainstorm docs, notes, guides, specs, designs, READMEs, or any markdown file output.
---

# Documentation Skill

When creating any written document, follow these principles.

## Always Write to a File

**Never dump long-form content to the terminal.** Always write to a `.md` file and tell the user where it is.

Use sensible naming - the topic and optionally a timestamp if uniqueness matters.

## Make It Readable

- Use headers to create structure
- Break up walls of text with bullets, lists, or tables
- Use code blocks for commands and configs
- Keep paragraphs short
- Use formatting (bold, code, etc.) to aid scanning

## Diagrams

When architecture, flows, or relationships would benefit from visualisation, use the `mermaid` skill.

## Tone

Match the document's purpose:
- Technical docs → clear and direct
- Proposals → persuasive but honest
- Brainstorms → exploratory, capture ideas freely
- Plans → actionable, concrete steps

## Emojis

Use emojis for visual navigation (section headers, callouts) when they help. Don't overdo it. Skip them entirely if the document is formal or technical.

## That's It

Don't overthink it. Write clearly, structure logically, output to a file.