project-readme-author

What this skill does

# README Author

Create READMEs that hook readers in 5 seconds, prove value in 30 seconds, and enable success in under 10 minutes.

## Operations

| Operation | Triggers | Purpose |
|-----------|----------|---------|
| **create** | No README exists, "create/generate README" | Build from scratch |
| **modify** | README exists, "update/change README" | Preserve structure, update sections |
| **validate** | "check/review/audit README" | Score against best practices |
| **optimize** | "improve/enhance README" | Fix issues, enhance quality |

### Operation Detection

Use the deterministic operation selector:

```bash
uv run shared/select_operation.py --skill project-readme-author --args "$ARGUMENTS" --check-files "README.md"
```

**Fallback rules (if script unavailable):**
1. Check `$ARGUMENTS` for explicit operation keywords
2. Check if README.md exists at target path
3. Default: `create` if no README, `modify` if README exists

---

## Create Operation

Use when building a README from scratch. Follow the Core Framework and Workflow sections below.

**Mandatory pre-draft checklist:**
- [ ] Archive status checked — `.archived.md` exists? If yes, archive notice goes first
- [ ] Aha moment identified — "What's the most impressive single thing?"
- [ ] Tagline crafted with emoji(s)
- [ ] At least one quantified metric (if available)
- [ ] Appropriate CTA tier determined

## Modify Operation

Use when updating an existing README while preserving its structure.

- **Keep custom prose** — user-written descriptions, explanations, context
- **Update dynamic content** — versions, badge URLs, install commands
- **Respect markers** — content within `<!-- custom -->...<!-- /custom -->` is never touched
- **Preserve section order** — don't reorder unless explicitly requested
- **Preserve manual notes** — any hand-written note, warning, tip that's factually relevant
- **Default to preservation** — when relevance is unclear, use AskUserQuestion to confirm
- **Never assume obsolescence** — only remove when explicitly asked or factually incorrect
- **Archive notice sync** — if `.archived.md` exists, ensure notice is present and current; if removed, remove the notice
- **Deprecated sections** — ask user via AskUserQuestion before removing

**When in doubt, preserve existing content and use AskUserQuestion to confirm before removing anything.**

## Validate Operation

Score an existing README against best practices. Run Essential → Professional → Elite → **Virality** checklists plus project-type specifics. See [references/validation-guide.md](references/validation-guide.md) for scoring format, tiers, project-type checks, and checklists.

**Scoring weights:** Essential 40%, Professional 25%, Elite 15%, Virality 20%

## Optimize Operation

**Quick Wins (auto-apply):** Center hero, add alt text, fix badge URLs, add TOC if >500 words, standardize badge style, fix heading hierarchy, add emojis to headers, add archive notice if `.archived.md` exists and notice is missing.

**Virality Quick Wins (auto-apply):**
- Add star badge if stars > 100
- Add download badge if downloads > 1000/week
- Format existing stats as quotable block

**Requires Approval:** Add new sections, rewrite tagline, change badge selection, remove emojis, restructure content order.

**Virality Suggestions (require approval):**
- Add curiosity hook to hero
- Restructure overview as pain point narrative
- Create comparison table vs alternatives
- Add tiered CTAs

---

## Core Framework: Hook → Prove → Enable → Extend

| Phase | Time | Purpose | Elements | Virality Trigger |
|-------|------|---------|----------|------------------|
| **Hook** | 0-3 sec | Instant recognition | Logo + badges + one-liner + demo visual | Curiosity gap + visual impact |
| **Prove** | 3-30 sec | Build credibility | Social proof, features, trust signals | Social proof + comparison wins |
| **Enable** | 30 sec - 5 min | Immediate success | One-liner install + working example | "I can do this" moment |
| **Extend** | Committed users | Deep engagement | Docs links, contributing, API reference | Share triggers + community |

**The goal: Time to first success under 10 minutes.** The first 5-10 lines visible without scrolling determine whether users stay or leave.

## Aha Moment Visualization

The "aha moment" is the single most impressive demonstration of your project's value. It must answer "What does this DO?" within 3 seconds.

### 3-Second Rule

The first visual element after the tagline must show transformation — before → action → after.

### Aha Patterns by Project Type

| Type | Aha Format | Example |
|------|------------|---------|
| **CLI** | Terminal GIF: before → command → after | ripgrep searching 1M files in 0.2s |
| **Library** | 3-line code with commented "wow" output | `# 50 lines → 3 lines` |
| **AI/ML** | Benchmark comparison chart | "2x faster than GPT-3" |
| **Web App** | GIF of core interaction loop | One-click deploy animation |

### Requirements

- **Show transformation** — what changes from input to output
- **Max 5 seconds** — attention drops sharply after this
- **Loop seamlessly** — GIFs should restart without jarring cuts
- **Placement** — immediately after tagline, before any text

### Identifying the Aha Moment

Ask: "What's the most impressive single thing this project does?" Then visualize it.

## Logo Generation (Mandatory)

Every README must have a logo:

1. **Check for existing logo** — look for `logo.png` at repo root; if found, skip to README generation
2. **Generate if missing** — invoke the **project-logo-author** skill
3. **Determine display size** — use `mcp__image-tools__get_image_metadata` to get width, then divide by 2 for retina display (e.g., 1024px → `width="512"`)

## Hero Section

The hero section must be center-aligned with these elements in order:

### Title Rule

**The title must be exactly the repository name.** Preserve original casing — `my-awesome-tool` stays `my-awesome-tool`, not "My Awesome Tool".

```markdown
<div align="center">
  <img src="logo.png" alt="Project Name" width="{DISPLAY_WIDTH}"/>

  [![Build](badge)](link) [![Version](badge)](link) [![License](badge)](link)

  **A clear, catchy one-liner that explains what this does and why it matters**

  [Documentation](url) · [Demo](url) · [Discord](url)
</div>
```

### Curiosity Hook (Optional)

A bold line placed after badges, before tagline, to create an information gap:

| Type | Example |
|------|---------|
| **Question** | "Ever spent 2 hours debugging what this fixes in 10 seconds?" |
| **Stat** | "Used by 50,000+ developers worldwide" |
| **Comparison** | "10x faster than grep for code search" |
| **Challenge** | "Find any file in your repo under 100ms" |

**Rules:**
- Must be verifiable (don't exaggerate)
- Connects to a real pain point
- Creates desire to learn more

### Hero Elements

| Element | Specification |
|---------|---------------|
| Logo | Width = half actual pixels (for retina), centered |
| Badges | 3-6 maximum, shields.io for consistency |
| Curiosity hook | Optional bold line creating information gap |
| Tagline | One sentence with emoji(s), max 350 chars (fits GitHub "About" field) |
| Quick links | Docs, demo, community (if available) |

### Tagline Rules

**The tagline is THE hook** — the single most critical line in your README. Users decide to stay or leave based on this one sentence. It must be short, witty, and instantly communicate what the project does.

**Bookend Emoji Pattern:**
- One emoji at START, one emoji at END
- Creates visual framing that draws the eye
- Reinforces the message from both sides

**Requirements:**
- **Max 350 characters** — ideal 80-150 chars, punchy and scannable
- **Instantly clear** — reader must understand what project does from this line alone
- **Source from pyproject.toml** — if `description` field exists, use as base and enhance. If crafting new, sync back.

**Great taglines (bookend pattern):**
- ✅ `🚀 Build production-ready APIs in minutes, not hours ⚡`
- ✅ `🔍 Fin