AwesomeReadme
Create GitHub READMEs that earn attention by telling a compelling story before diving into installation and reference material.
Core philosophy: Story before installation. Hook before documentation.
Workflow Routing
When you execute a workflow, start with this exact notification:
Running the **WorkflowName** workflow from the **AwesomeReadme** skill...
Route requests like this:
| Workflow |
Trigger |
File |
| Create |
create readme, write readme, new readme |
workflows/Create.md |
| Improve |
improve readme, make readme better, rewrite readme, more compelling |
workflows/Improve.md |
| Analyze |
analyze readme, review readme, readme feedback, audit readme |
workflows/Analyze.md |
Load the matching workflow file with the read tool before proceeding.
Pi Adaptation Notes
- Use normal conversation questions instead of
AskUserQuestion.
- If visual content is requested and no image-generation or art skill is available, produce Mermaid diagrams, ASCII diagrams, or clear image placeholders in
docs/.
- Use the
read tool to inspect files such as README.md, package.json, CLAUDE.md, and docs.
- Use
bash only for quick directory inspection or metadata gathering.
- Preserve technical accuracy while improving structure, clarity, and emotional pull.
- Default to editing
README.md unless the user specifies a different file.
README Structure for Stars
The default structure should be:
- Hero section - tagline, badges, one-line breakthrough
- The problem - pain the reader recognizes immediately
- The insight - the realization that makes the project different
- The solution - short explanation of what the project is
- See it in action - demo, screenshot, GIF, or code sample
- Features / defense - benefit-focused table
- Quick start - only after the reader is hooked
- How it works - deeper technical explanation
- The story - why the project exists
- Footer - roadmap, contributing, license, CTA
Hooks That Work
- Stop [doing painful thing]. Start [doing better thing].
- The first [category] that [unique benefit].
- [Things] can lie. [Tests or proof] cannot.
What Not to Do
- Lead with installation instructions
- Bury the story at the bottom
- Open with technical jargon before emotional context
- Skip visual hierarchy
- End without a clear call to action
References
1---2name: awesome-readme3description: Creates, improves, and reviews GitHub README files using a story-first, engagement-focused structure. Use when asked to write a new README, rewrite an existing README to be more compelling, or analyze a README for clarity, differentiation, and star-worthiness.4---56# AwesomeReadme78Create GitHub READMEs that earn attention by telling a compelling story before diving into installation and reference material.910**Core philosophy:** Story before installation. Hook before documentation.1112## Workflow Routing1314When you execute a workflow, start with this exact notification:1516```text17Running the **WorkflowName** workflow from the **AwesomeReadme** skill...18```1920Route requests like this:2122| Workflow | Trigger | File |23|----------|---------|------|24| **Create** | create readme, write readme, new readme | `workflows/Create.md` |25| **Improve** | improve readme, make readme better, rewrite readme, more compelling | `workflows/Improve.md` |26| **Analyze** | analyze readme, review readme, readme feedback, audit readme | `workflows/Analyze.md` |2728Load the matching workflow file with the `read` tool before proceeding.2930## Pi Adaptation Notes3132- Use normal conversation questions instead of `AskUserQuestion`.33- If visual content is requested and no image-generation or art skill is available, produce Mermaid diagrams, ASCII diagrams, or clear image placeholders in `docs/`.34- Use the `read` tool to inspect files such as `README.md`, `package.json`, `CLAUDE.md`, and docs.35- Use `bash` only for quick directory inspection or metadata gathering.36- Preserve technical accuracy while improving structure, clarity, and emotional pull.37- Default to editing `README.md` unless the user specifies a different file.3839## README Structure for Stars4041The default structure should be:42431. **Hero section** - tagline, badges, one-line breakthrough442. **The problem** - pain the reader recognizes immediately453. **The insight** - the realization that makes the project different464. **The solution** - short explanation of what the project is475. **See it in action** - demo, screenshot, GIF, or code sample486. **Features / defense** - benefit-focused table497. **Quick start** - only after the reader is hooked508. **How it works** - deeper technical explanation519. **The story** - why the project exists5210. **Footer** - roadmap, contributing, license, CTA5354## Hooks That Work5556- Stop [doing painful thing]. Start [doing better thing].57- The first [category] that [unique benefit].58- [Things] can lie. [Tests or proof] cannot.5960## What Not to Do6162- Lead with installation instructions63- Bury the story at the bottom64- Open with technical jargon before emotional context65- Skip visual hierarchy66- End without a clear call to action6768## References6970- [Best-README-Template](https://github.com/othneildrew/Best-README-Template)71- [awesome-readme](https://github.com/matiassingers/awesome-readme)72- [shields.io](https://shields.io) for badges73- [vhs](https://github.com/charmbracelet/vhs) for terminal GIFs
aojdevstudio