# Markdown Writer

> 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.

- Skill: `majiayu000/markdown-writer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/markdown-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/markdown-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/markdown-writer

---


# 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