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

Analyze Workflow

Review a README and provide actionable feedback without making changes.

Step 1: Read the README

Read README.md or the user-specified README file.

Step 2: Score Key Criteria

Rate each criterion from 1-10.

Scoring Rubric

Score Card Format

## README Analysis: [Project Name]

| Criterion | Score | Max |
|-----------|-------|-----|
| Hook Strength | X | 10 |
| Problem Clarity | X | 10 |
| Unique Insight | X | 10 |
| Visual Hierarchy | X | 10 |
| Story Presence | X | 10 |
| Technical Clarity | X | 10 |
| CTA Effectiveness | X | 10 |
| **Total** | **XX** | **70** |

Rating Bands

• 60-70: Star-worthy
• 45-59: Good, needs polish
• 30-44: Average, significant improvements needed
• Below 30: Major rewrite recommended

Step 3: Identify Specific Issues

Structure Analysis

• What section appears first?
• Where is installation?
• Is there a story, and is it prominent?
• Are there visuals or diagrams?

Content Analysis

• Is the problem clearly stated?
• Is there a unique insight?
• Are features benefit-focused?
• Is there a clear CTA?

Technical Analysis

• Are prerequisites clear?
• Is installation copy-pasteable?
• Are examples coherent?
• Do links and references look valid?

Step 4: Generate Recommendations

For each issue, use this format:

### Issue: [Name]

**Current:** [What the README does now]

**Problem:** [Why this hurts engagement or clarity]

**Fix:** [Specific action to take]

**Example:**
[Before/after snippet when useful]

Priority Levels

Step 5: Deliver Analysis Report

Use this structure:

# README Analysis Report

## Summary
[2-3 sentence overview]

## Score: XX/70 ([Rating])

## Top 3 Issues to Fix

### 1. [Highest impact issue]
[Details]

### 2. [Second issue]
[Details]

### 3. [Third issue]
[Details]

## Quick Wins (P0)
- [ ] [Quick fix 1]
- [ ] [Quick fix 2]

## Medium-Term Improvements (P1)
- [ ] [Improvement 1]
- [ ] [Improvement 2]

## Nice-to-Haves (P2-P3)
- [ ] [Optional improvement]

## What Is Working Well
- [Positive 1]
- [Positive 2]

Important Notes

• This workflow is analysis only. Do not modify the README.
• Be specific. Avoid generic advice.
• Focus on improvements that increase clarity, differentiation, and engagement.
• If the user wants changes after analysis, switch to the Improve workflow.

Create Workflow

Create a compelling, story-driven README from scratch.

Step 1: Gather Context

Before writing anything:

1. Read existing documentation: README.md, CLAUDE.md, package.json, and relevant docs. 2. Identify the tech stack. 3. Find the core problem the project solves. 4. Discover the unique insight or mechanism. 5. Inspect the repo structure if needed to confirm key features.

Recommended inspection order:

• README.md if it exists
• package.json or equivalent project metadata
• CLAUDE.md or other agent/docs files
• docs/ contents
• Key source entry points

Step 2: Ask About Visual Content

Ask the user plainly:

Would you like visual content in the README? Options: create new visuals, use existing images, or keep it text-only.

If the user wants visuals:

• Decide which visuals are needed: architecture, workflow, hero graphic, feature comparison.
• Prefer existing images if they already exist.
• If no art/image tool is available, generate Mermaid or ASCII diagrams, or insert clear placeholders for later assets.

Step 3: Identify the Emotional Hook

Find the pain point that resonates.

Hook Formula

[Target audience] experiences [painful problem].
Current solutions fail because [reason].
This project solves it by [unique approach].

Example Hooks

Step 4: Structure the README

Follow this order.

1. Hero

<div align="center">

# Project Name

### **[Provocative tagline]**

[![License](badge)](link)
[![PRs Welcome](badge)](link)

*One sentence that captures the breakthrough.*

[**Demo**](#demo) · [**Quick Start**](#quick-start) · [**Docs**](link)

</div>

2. The Problem

## The Problem Everyone Ignores

[Paint the painful scenario in 3-4 sentences]

- Failure mode 1
- Failure mode 2
- Failure mode 3

**Sound familiar?**

> *"Relatable scenario or quote"*

3. The Insight

## The Insight That Changed Everything

[Build up to the breakthrough]

<div align="center">

### **[First half of insight]**
### **[Second half of insight]**

</div>

[Explain why this matters]

4. The Solution

## Introducing [Project Name]

[One sentence describing what it is]

| Component | Role |
|:----------|:-----|
| **Part A** | What it does |
| **Part B** | What it does |
| **Part C** | What it does |

[Diagram, image, Mermaid, or ASCII block]

5. Demo

## See It In Action

<details>
<summary><b>Demo: [What the demo shows]</b></summary>

[GIF, screenshot, or code example]

</details>

6. Features / Defense

## Why It Wins

| Feature | What It Does | Why It Matters |
|:--------|:-------------|:---------------|
| **1** | Mechanism | Prevents or enables X |
| **2** | Mechanism | Prevents or enables Y |

7. Quick Start

## Quick Start

### Prerequisites
[Minimal list]

### Install
[Short install sequence]

### Run
[Show the happy path]

8. How It Works

## How It Works

[Architecture explanation]

### The Core Loop
[Code or pseudocode]

9. The Story

## The Story Behind [Project]

[Why it was built]
[What frustrated the author]
[What was discovered]

10. Footer

## Roadmap
- [x] Completed feature
- [ ] Planned feature

## Contributing
[Brief guidelines]

## License
[License type]

---

<div align="center">

**[Memorable closing line]**

If this helped you, star the repo.

</div>

Step 5: Create Visuals If Requested

If visuals are needed:

• Use existing assets first.
• Otherwise create Mermaid/ASCII diagrams or use an available art/image skill.
• Save generated files in docs/ when creating new assets.
• Reference every asset with clear alt text.

Step 6: Write and Deliver

1. Write the complete README. 2. Keep all technical details accurate. 3. Replace placeholders with real project details. 4. Infer GitHub links from the repo when possible. 5. Validate that headings, links, and file references are coherent.

Quality Checklist

• [ ] Hook comes before installation
• [ ] Story is not buried
• [ ] Visual hierarchy is strong
• [ ] README includes a CTA
• [ ] Technical instructions are still correct
• [ ] Images or diagrams are referenced correctly
• [ ] Links and paths look valid

Improve Workflow

Transform an existing README into a more compelling, star-worthy narrative.

Step 1: Read the Existing README

Read README.md or the file the user specifies.

Identify:

• Where installation appears
• Whether there is a clear hook
• Whether the README explains the problem
• Whether there is a story or origin narrative
• Whether visuals or diagrams exist

Step 2: Diagnose Weaknesses

Common README Problems

Score the README

Step 3: Ask About Visual Content

Ask the user plainly:

Should I add new visuals, keep the current visuals only, or make this text-only?

If the user wants new visuals:

• Add diagrams where they increase comprehension.
• Use existing assets if they are good enough.
• If no art/image tool is available, produce Mermaid or ASCII diagrams.

Step 4: Identify the Core Transformation

Find what makes the project different.

Discovery Questions

1. What frustrated the author enough to build this? 2. What is the breakthrough realization? 3. What failure mode does this prevent? 4. Who feels the pain most sharply?

Transformation Formula

BEFORE: [What users suffer through now]
INSIGHT: [The breakthrough realization]
AFTER: [How life is better with this project]

Step 5: Restructure

Use this order:

1. Hero 2. The Problem 3. The Insight 4. The Solution 5. Demo 6. Features 7. Quick Start 8. How It Works 9. The Story 10. Footer

Step 6: Rewrite

For each section: 1. Preserve technical accuracy. 2. Rewrite passive language into active language. 3. Add visual hierarchy with tables, callouts, details blocks, or diagrams. 4. Put emotional resonance before deep technical detail.

Rewriting Principles

Step 7: Add Visuals If Requested

If the user wants new visuals:

• Create architecture or workflow diagrams where they clarify the README.
• Save new assets in docs/ when appropriate.
• Use alt text and keep references consistent.

Step 8: Validate and Deliver

Checklist

• [ ] Hook is near the top
• [ ] Installation is not the opening section
• [ ] Story is prominent
• [ ] Visual hierarchy is stronger than before
• [ ] CTA exists in the footer or hero
• [ ] Technical instructions still work
• [ ] Links and asset references look valid

Deliver

Present: 1. The rewritten README 2. A short summary of structural changes 3. The strongest improvements made