---
name: markdown-writer
description: |
  Edit and create markdown files with consistent style. Use when:
  (1) Creating or updating README files, (2) Editing documentation,
  (3) Writing DONE.md, PLAN.md, RESEARCH.md, (4) Any .md file edits.
  Follows Paul Graham writing style: short sentences, direct claims, no hedging.
category: documentation
user-invocable: true
allowed-tools: Read,Write,Glob,Grep
---

# Markdown Writer

Edit markdown files with consistent tone and style.

## When to Use

- README.md updates
- Documentation in /docs folders
- Project status files (DONE.md, PLAN.md, RESEARCH.md)
- Any .md file that needs clear, direct writing

## Writing Style

**Voice**
- Write like speaking to an intelligent friend
- Short sentences. Direct claims. No hedging.
- First person for opinions and experience
- Active voice, not passive
- State claims confidently. No waffling.

**Punctuation Rules**
- **Never use em dashes (—)**
- Use periods and new sentences for separate thoughts
- Use commas for simple asides
- Use parentheses for clarifying information
- Use colons for lists or elaboration

**Structure**
- Start with the point, not background
- One idea per paragraph
- Headers should be claims, not topics
- End sections when the point is made

**Technical Writing**
- Code examples should be minimal and functional
- Explain the why, not just the what
- Link to deeper resources rather than over-explaining

## Quality Checklist

Before finalizing:

- [ ] No em dashes in content
- [ ] Sentences are short and direct
- [ ] Opens with the main point
- [ ] Code examples are minimal
- [ ] Tables used for structured data
- [ ] Lists used for sequences or options