github-readme-overhaul

Files (9)

• SKILL.md
• openai.yaml · agents/
• badges.md · references/
• copy-patterns.md · references/
• infographics.md · references/
• quality-gate.md · references/
• strategy.md · references/
• terminal-demo.md · references/
• visual-system.md · references/

SKILL.md (first lines)

# GitHub README Overhaul

Turn a README into a GitHub-native conversion surface: visitors should understand the pain, see the fix, trust the proof, and know how to install within the first screen.

## Core Behavior

When the user asks for a compelling README, the agent should rewrite the README as a branded mini case study with clear install intent, infographic-level visual proof, and tight copy, even if the user says "landing page," "viral," or "pull out all the stops." Borrow landing-page strategy, but do not create a fake website inside Markdown or walls of text.

## Required Inputs

Inspect the repo before writing:

1. Existing `README.md`, package metadata, manifests, screenshots, docs, examples, CI, releases, and install paths.
2. Product category: CLI, library, app, extension, agent skill, MCP server, GitHub Action, plugin, template, SaaS, or internal tool.
3. Real proof: terminal demo video/GIF, screenshot, terminal output, benchmark, before/after, testimonials, stars/downloads, examples, supported platforms.
4. Install path: one command, marketplace link, package manager, Docker, browser extension store, VS Code Marketplace, Claude plugin install, GitHub template, or hosted URL.

If proof is missing, create a placeholder task or asset brief, but do not invent metrics.

## Above-the-Fold Formula

Use this order unless the repo strongly suggests a better one:

1. Logo or compact wordmark if available.
2. H1 with product name.
3. Tagline that names the painful job and the promised outcome.
4. Badge row with only meaningful, maintained badges.
5. Hero proof: terminal demo, screenshot, terminal panel, flow diagram, benchmark chart, or before/after graphic.
6. One-line install or primary CTA.
7. Three concrete value bullets.

The first screen should answer: "What is this, why do I care, can I trust it, and how do I try it?"

## Reference Router

Read only what the task needs:

| File | When to Read |
| --- | --- |
| `references/strategy.md` | README narrative, conversion structure, viral/adoption mechanics |
| `references/badges.md` | Badge selection, ordering, sources, and anti-spam rules |
| `references/visual-system.md` | Hero graphics, screenshots, diagrams, GitHub rendering constraints |
| `references/infographics.md` | Compelling README infographics, proof graphics, and visual density rules |
| `references/terminal-demo.md` | Terminal demo video/GIF planning, recording, scripting, export, and embedding |
| `references/copy-patterns.md` | Taglines, pain-point framing, CTAs, section copy patterns |
| `references/quality-gate.md` | Final review checklist and failure modes |

## README Structure

Default section order:

```markdown
<brand/logo>

# Product Name

> Pain-point tagline with outcome.

<badge row>

<hero proof visual>

<install command or marketplace CTA>

## Why this exists
## See it work
## Install
## Quick start
## What you get
## Examples
## How it works
## Configuration
## Comparisons / tradeoffs
## Roadmap
## Contributing
## License
```

Collapse or reorder sections when the product needs a simpler path. For libraries, quickstart moves higher. For visual tools, screenshots move higher. For developer tools, terminal proof moves higher.

## Visual Rules

- Design for GitHub Markdown rendering, dark/light mode, mobile width, and skim reading.
- Prefer a sequence of strong proof visuals over long explanatory sections.
- Use actual product UI, terminal output, diagrams, or screenshots when possible.
- For CLI/dev tools, strongly consider a short terminal demo as the hero proof.
- For complex developer tools, use infographic blocks like before/after, architecture, savings, workflow, and supported surfaces.
- Store assets under `assets/readme/` or the repo's existing docs asset folder.
- Use Mermaid for maintainable diagrams when it fits.
- Use SVG/PNG only when visual polish matters or Mermaid is too limited.
- For generated visuals, prompt for "GitHub README documentation graphic, not a website."

Do not add nav bars, pricing cards, fake CTA buttons, huge landing-page sections, or marketing graphics that do not explain the product.

## Copy Density Rules

- Replace paragraphs with labeled visuals, short callouts, tables, and examples.
- Keep each section to one job: pain, proof, install, example, or detail.
- Lead sections with the sharpest claim, then prove it visually.
- Prefer one memorable sentence over three explanatory paragraphs.
- If a README already looks visually strong, improve wording, ordering, and proof clarity without flattening the visual system.

## Badge Rules

Use badges as trust signals, not decoration. Prefer:

- package version/downloads
- CI/build
- test coverage only if true and maintained
- license
- marketplace/version/install count
- docs
- supported runtime/platform
- security/audit status when real

Avoid badge soup. Five to eight strong badges usually beat twenty weak ones.

## Viral / Adoption Mechanics

From joeblackwaslike/agent-skills, MIT.

More from joeblackwaslike/agent-skills