Readme

Bad: "A DevOps layer implementing the Three Ways for agent workflows." Good: "Coding agents forget everything between sessions. This fixes that."

The reader should understand what pain you solve in one sentence. No jargon, no framework names, no theory. The problem is the hook. (Note: framework references like Three Ways and Meadows belong in the body as design rationale — just don't lead with them.)

2. Acknowledge prior art

If your approach resembles established practices (agile, SCRUM, spec-driven development, CI/CD), say so explicitly:

"If you've done X, you already know the fix. What's new is Y."

This disarms experienced practitioners who would otherwise dismiss you as reinventing the wheel. Claim only what's genuinely novel.

3. Show, don't claim

Bad: "This is what makes X different. The system compounds." Good: A terminal transcript showing the system working.

Assertions without evidence trigger hostility. Concrete examples > adjectives. If you can't show it in a code block, it's not ready for the README.

4. State your differentiator once

One clear explanation. One demonstration. That's the max. Repeating your core value proposition in every section crosses from reinforcement into marketing copy. Trust the reader to absorb it the first time.

5. Trust block near install

Before a user installs anything that runs code, hooks, or modifies config, they need to see:

This goes near the install command, not buried in an FAQ.

6. Collapse depth, don't delete it

Detailed workflow steps, architecture deep-dives, theory, and reference material belong in <details> blocks. Skimmers get the fast path. Deep readers click to expand. Never delete depth to achieve brevity — collapse it.

7. Strip guru tone

No "What N months taught me." No "I come from X, so I applied Y." No "This is what makes us different." Let the tool speak for itself. Humility disarms. Condescension repels.

8. Section order serves adoption

Problem → Install → See It Work → Getting Started Path → How It Works (collapsed) → Reference

Theory and architecture come AFTER the user has seen examples and knows how to start. Never put "why this is important" before "how to try it."

Execution Steps

Given /readme [--rewrite] [--validate]:

Step 1: Pre-flight

ls README.md 2>/dev/null

Mode detection:

• --validate + README exists → skip to Step 5 (council validation only)
• --rewrite + README exists → read existing, use as context for rewrite
• README exists, no flags → ask:
  • "Rewrite — regenerate with gold-standard patterns"
  • "Validate — council-check the existing README"
  • "Cancel"
• No README exists → proceed to Step 2 (generate from scratch)

Step 2: Gather Context

Read available project files silently (no output to user):

ls README.md PRODUCT.md package.json pyproject.toml go.mod Cargo.toml Makefile 2>/dev/null
ls -d src/ lib/ cmd/ app/ 2>/dev/null
ls -d docs/ 2>/dev/null
ls LICENSE CHANGELOG.md 2>/dev/null

Extract:

• Project name from manifest files
• Language/runtime from build files
• Existing description from README or PRODUCT.md
• License from LICENSE file
• Install method from manifest (npm, pip, brew, go install, cargo, etc.)

Step 3: Interview

Use AskUserQuestion for each section. Pre-populate suggestions from Step 2 where possible. Keep questions short.

3a: The Problem

Ask: "What problem does this solve? One sentence — what pain does your user have?"

Options (derived from existing README/PRODUCT.md if available):

• Suggested problem statement
• A punchier variant
• "Let me type my own"

3b: The Fix

Ask: "How does it fix that problem? One sentence — what does your tool actually do?"

3c: Who Is It For

Ask: "Who is this for? Name the runtime, framework, or role."

Example: "Python developers using FastAPI" or "Anyone running Claude Code or Cursor"

3d: Install

Ask: "What's the install command? (We'll put this front and center)"

Options:

• Detected from manifest (e.g., npm install <pkg>, pip install <pkg>)
• "Let me type my own"

3e: Quick Demo

Ask: "What's the simplest thing a user can do after installing to see it work? (A command, a code snippet, or a terminal session)"

3f: Trust Concerns

Ask: "Does your tool do any of these? Check all that apply."

• Runs shell commands or hooks
• Modifies config files outside the project
• Makes network calls
• Creates files in the user's repo
• None of the above

3g: Prior Art (optional)

Ask: "Are there similar tools? If so, how is yours different? (Be honest — readers who know the space will check)"

Options:

• "Yes, let me describe" → follow up
• "Not really / I'll skip this"

Step 4: Generate README

Using the interview responses and the 8 patterns above, generate the README with this structure:

<div align="center">

# {Project Name}

### {Problem statement — one line}

{Badges}

{Nav links}

</div>

---

> [!IMPORTANT]
> {Trust block — local-only, what it touches, how to disable, how to uninstall}
> (Skip if no trust concerns from 3f)

{Install command}

---

## The Problem

{2-3 sentences expanding the problem. Acknowledge prior art if applicable.
State what's genuinely new about your approach — once.}

---

## See It Work

{Terminal transcript or code example from 3e. Show, don't describe.}

---

## Install

{Full install details, alternative methods in <details> blocks.
"What it touches" table if trust concerns exist.}

---

## Getting Started

{Adoption path — Day 1, Week 1, etc. Or just "Run X, then Y."}

---

## How It Works

{One paragraph summary + diagram if applicable.}

<details>
<summary><b>Details</b> — {phases, architecture, etc.}</summary>

{Deep content here}

</details>

---

## {Reference sections as needed}

{Skills, API, CLI, etc. — collapsed where appropriate}

---

## FAQ

{Top 3 questions inline, link to full FAQ if it exists}

---

## Contributing

## License

Generation rules:

• Every <details> block must have a blank line after <summary> (enables markdown rendering)
• Use markdown inside details blocks, not inline HTML (<code>, <a href>, <br>)
• Trailing blank line before </details>
• No emoji unless the user's existing content uses them
• Flywheel/differentiator concept: state ONCE in "The Problem", demonstrate ONCE in "See It Work"
• Never use phrases: "What N months taught me", "This is what makes X different", "I come from X so I applied Y"

Write the generated README to README.md.

Step 5: Council Validation

Run a council to validate the README:

Skill(skill="council", args="--quick validate README.md — is it clear, non-repetitive, and does it serve both skimmers and deep readers?")

If --rewrite or generating from scratch: Use --quick (inline, fast).

If --validate on existing README: Use default council (2 judges) for thorough review.

Present the council findings to the user. If significant issues found, offer:

• "Fix — apply council recommendations automatically"
• "Show me — display findings, I'll decide"
• "Ship it — good enough"

Step 6: Apply Fixes (if requested)

Apply council-recommended fixes. Re-validate with --quick to confirm.

Step 7: Report

## README Complete

**File:** README.md
**Sections:** {count}
**Patterns applied:** {list which of the 8 patterns were relevant}
**Council verdict:** {PASS/WARN/FAIL}

{If WARN/FAIL: list the top findings and whether they were fixed}

Anti-Patterns to Detect

When rewriting or validating, flag these:

Examples

Generating a README from scratch for a new project

User says: /readme

What happens:

1. Pre-flight detects no existing README.md and proceeds to generate from scratch.
2. The skill reads project context (manifest files, source directories, license) and runs a short interview asking about the problem, the fix, the audience, install command, quick demo, and trust concerns.
3. A README is generated following all 8 gold-standard patterns (problem-first lead, trust block near install, collapsed depth, etc.) and validated by a quick council review.

Result: A complete README.md written to disk that converts skimmers into users and serves deep readers, with a council verdict confirming quality.

Validating an existing README without changes

User says: /readme --validate

What happens:

1. Pre-flight confirms README.md exists and enters validate-only mode, skipping the interview and generation steps.
2. A full council review (2 judges) evaluates the README against the 8 patterns and the anti-pattern detection table (flywheel echo, guru tone, buried trust info, etc.).
3. Findings are presented with options to auto-fix, review manually, or ship as-is.

Result: A detailed council report identifying specific anti-patterns and structural issues in the existing README, with actionable fix suggestions.

Troubleshooting

See Also

• skills/product/SKILL.md — PRODUCT.md generation (feeds into README context)
• skills/doc/SKILL.md — Code documentation (different scope — API docs, not README)
• skills/council/SKILL.md — Validation engine used in Step 5