--- name: github-readme-overhaul-6d7fbae62e2a description: Use when writing, rewriting, branding, visually overhauling, or optimizing a GitHub README.md for installs, downloads, stars, marketplace conversion, OSS adoption, or immediate product value, including badges, hero graphics, tagline, pain-point messaging, quickstart, terminal demos, screenshots, GIFs/videos, and README-native visual assets. metadata: last_updated: "2026-05-26" --- # 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 # Product Name > Pain-point tagline with outcome. ## 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 Optimize for immediate value, not begging people to share: - Show the pain in the first sentence. - Show proof before abstractions. - Make install copy-pastable. - Include a "see it work" example near the top. - Give users a reason to star through utility: roadmap, examples, templates, updates, or reference value. - Make screenshots and terminal snippets visually memorable. - Use a short terminal demo to show time-to-value when the tool is command-driven. - Make the README easy to quote by using sharp, specific phrasing. Do not ask readers to share. Do not manufacture hype. Do not exaggerate capabilities. ## Completion Gate Before saying the README is done: 1. Verify every install command, badge URL, image path, and internal link that can be checked locally. 2. Confirm no invented metrics, fake screenshots, or unsupported claims were added. 3. Check GitHub Markdown constraints: image sizes, table readability, dark/light compatibility, no broken relative paths. 4. Ensure the first screen contains pain, product, proof, and install path. 5. Report what was verified and what still needs a live GitHub render or asset generation pass. ## Red Flags Stop and revise if you catch: - "This would look great as a website." - "We can add badges for everything." - "No proof exists, so I'll imply traction." - "The install command is probably right." - "The hero graphic is pretty but does not explain anything." - "The README asks for stars or shares before showing value." - "This section is becoming a wall of text." - "The visuals are strong, so the copy can stay vague." --- Source attribution: joeblackwaslike Original project: https://github.com/joeblackwaslike/agent-skills/blob/5ee9024524879d0fa619846a5a1e092964561dcf/skills/github-readme-overhaul/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2026 Joe Black Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: joeblackwaslike Original project: https://github.com/joeblackwaslike/agent-skills/blob/5ee9024524879d0fa619846a5a1e092964561dcf/skills/github-readme-overhaul/SKILL.md Attribution basis: Source repository record Fields of work: Design, Marketing Roles: Content Marketer, Growth Marketer, Product Marketer, SEO Specialist, UX Designer Specialties: Backend, Design, DevOps, Word Documents, Frontend, Git, Mobile, Remotion, Testing Tools: GitHub Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: e0182f9bebc66a4d7cea8432d0c25c282a38f2cab02991c179053c2a2c35d545