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