readmelisted

# $readme — Gold-Standard README Generation > **Purpose:** Generate a README that converts skimmers into users and satisfies deep readers — then validate it with a council. **YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.** ## Quick Start ```bash $readme # Interview + generate + validate (new README) $readme --rewrite # Rewrite existing README with same patterns $readme --validate # Council-validate an existing README without rewriting ``` --- ## The Patterns These are non-negotiable. Every README this skill produces follows them. ### 1. Lead with the problem, not the framework 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 tran