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