Readme
Interview-driven README drafting or rewrite that leads with the user pain, then council-validates before you ship or open-source.
Overview
Readme is an agent skill most often used in Build (also Ship, Launch) that drafts or rewrites gold-standard README.md files and validates them with a council.
Install
npx skills add https://github.com/boshu2/agentops --skill readmeWhat is this skill?
- Non-negotiable patterns: problem-first hook, skimmer-to-user conversion, deep-reader satisfaction
- /readme, /readme --rewrite, and /readme --validate flows with mandatory execution (not description-only)
- Council dependency for validation pass on generated or existing READMEs
- Aligns with code-complete, wiki-knowledge-surface, and pragmatic-programmer practices
- Fork context window with HISTORY excluded for focused task runs
- 3 /readme command variants (default, --rewrite, --validate)
- Output contract: README.md
Adoption & trust: 762 installs on skills.sh; 384 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your project works, but the README opens with framework buzzwords and fails to convert visitors or satisfy serious evaluators.
Who is it for?
Solo maintainers of agents, CLIs, or libraries who need a credible README before sharing the repo publicly.
Skip if: Teams that only need auto-generated API docs from code comments with no narrative positioning, or who already have a locked brand copy deck and legal-reviewed readme.
When should I use this skill?
User asks to draft or improve README docs, run /readme, or needs problem-first open-source documentation with validation.
What do I get? / Deliverables
You get an interview-shaped README.md that leads with the problem and passes council validation—ready to commit before wider distribution.
- README.md
- Council validation outcome on README quality
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build/docs is the canonical shelf because the output contract is README.md and the skill optimizes repo-facing documentation quality, not runtime code. Docs subphase fits the gold-standard README patterns, /readme CLI entry points, and explicit documentation output_contract in skill metadata.
Where it fits
Generate README.md after core features land so contributors see pain-first positioning instead of internal jargon.
Rewrite README before tagging a release so install instructions and value prop match what you actually ship.
Validate an existing README with --validate before posting the repo to HN or Product Hunt.
How it compares
A workflow skill for narrative README quality with validation—not a static template paste or MkDocs generator.
Common Questions / FAQ
Who is readme for?
Indie builders and small teams maintaining repos where README.md is the primary discovery and trust surface for agents, CLIs, and open tooling.
When should I use readme?
Use it during Build/docs when drafting or rewriting README; again in Ship before release tags; and at Launch when positioning must convert new visitors—use --validate when copy exists but quality is uncertain.
Is readme safe to install?
Check the Security Audits panel on this Prism page; the skill writes documentation locally and depends on council—review what council invokes in your AgentOps setup.
Workflow Chain
Requires first: council
SKILL.md
READMESKILL.md - Readme
# /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 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: | Concern | Answer it | |---------|-----------| | What does it touch? | Files created/modified, hooks registered | | Does it exfiltrate? | Telemetry, network calls, data leaving the machine | | Permission surface | Shell commands, config changes, git behavior modifications | | Reversibility | How to disable instantly, how to uninstall completely | 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 ```bash 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 — regenera