aojdevstudio/agentic-utilities/awesome-readme

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:

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:

1. Hero section - tagline, badges, one-line breakthrough
2. The problem - pain the reader recognizes immediately
3. The insight - the realization that makes the project different
4. The solution - short explanation of what the project is
5. See it in action - demo, screenshot, GIF, or code sample
6. Features / defense - benefit-focused table
7. Quick start - only after the reader is hooked
8. How it works - deeper technical explanation
9. The story - why the project exists
10. 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

• Best-README-Template
• awesome-readme
• shields.io for badges
• vhs for terminal GIFs