readme-best-practices

Your README is a landing page. You have 5 seconds before someone closes the tab. This plugin teaches
your AI agent to write READMEs that hook the reader and make them install.
> Every coding assistant defaults to dry, template-style documentation. This plugin changes that.
> Bold punchlines up front, scannable feature tables, copy-paste Quick Start blocks, visual author
> cards. The structure that top open source projects use, applied automatically.
Install
Cursor / Claude Code / Windsurf
Or copy skills/ into your .cursor/skills/ or .claude/skills/ directory.
What's Included
| Type | Name | Description |
| ------- | ----------------------- | ---------------------------------------------------------------------- |
| Skill | readme-best-practices | Full guide: BLUF headers, story sections, feature tables, author cards |
| Rule | readme-best-practices | Always-on rule that enforces great README patterns on every edit |
| Command | /create-readme | Create or rewrite the project README following the full best practices |
The Transformation
| Before | After |
| ---------------------------------- | ------------------------------------------------------------------------- |
| Generic "A tool that..." opening | BLUF punchline: bold value prop in the first 3 lines |
| Section called "The Problem" | A name with personality: "Your Agent Works in a Void" |
| **Feature:** description bullets | Feature tables, scannable at a glance |
| Plain "Made by username" | Visual author card with avatar and stats (GitShow) |
| Quick Start with $ prefix | Copy-paste ready bash blocks |
| All paragraphs the same length | Varied structure: one-liners, short paragraphs, tables |
| Missing demo GIF link | Assets verified on disk before referencing |
How It Works
The plugin embeds a complete README structure into your agent's behavior:
1. **BLUF header** - bold punchline first, context second. The reader decides in 3 seconds
2. **Navigation buttons** - for-the-badge style, linking to key sections
3. **Story section** - named with personality, not "Introduction" or "Overview"
4. **Feature tables** - scannable, two-column format instead of bullet lists
5. **Copy-paste Quick Start** - zero to running in under 30 seconds