Repo Glowup

Repo Glow-Up

What this skill is for

Most repos that get ignored on GitHub aren't ignored because the code is bad — they're ignored because a visitor can't tell what the project does, whether it works, or whether it's alive, within the first 10-15 seconds on the page. This skill turns that first impression into something concrete and fixable: a scored audit, a rewritten README, and launch copy — grounded in the actual repo content, never invented.

Read references/scoring-rubric.md before scoring — don't wing the weights from memory.

Guardrails (read first)

This skill is about making a real project easier to understand and trust — not about gaming a platform. Hold to this line even if the user pushes back:

• Never fabricate metrics, testimonials, benchmark numbers, download counts, or "used by" claims that aren't in the repo or confirmed by the user. A README that oversells gets called out publicly and does more damage than a modest one.
• Never suggest buying stars, star-exchange groups/rings, bot traffic, or coordinated fake accounts. These violate GitHub's terms, can get a repo banned, and are the opposite of durable growth.
• Never suggest astroturfing (fake reviews/comments/upvotes on HN, Reddit, Product Hunt). Real platforms actively detect and punish this.
• Do suggest everything that is legitimate growth work: clarity, visual proof, honest positioning, comparison to real alternatives, cross-posting to the right communities, timing, and asking real early users to star/share.
• If the repo doesn't actually do what the user wants to claim, say so and suggest the honest framing instead of a punchier but false one.

Workflow

1. Get the repo content

Figure out what you're working with, in order of preference:

• Local checkout available (the user is working in the repo, or it's on their connected device/filesystem): read the files directly — README.md, LICENSE*, CONTRIBUTING*, .github/, image assets, package.json/pyproject.toml/etc. for install commands, and git log -5 --oneline / git remote -v for activity and identity.
• Only a GitHub URL: use gh api repos/{owner}/{repo} if the gh CLI is authenticated, otherwise fetch the repo page and raw README via web fetch. You won't get everything this way (e.g. exact file tree) — note what you couldn't check rather than guessing.
• User pastes README text directly: work from that, but ask whether there's a repo link too, since topics/description/badges live outside the README.

Then run scripts/scan_repo.py <path-or-nothing> against a local checkout — it collects the objective, checkable signals (README length and headings, image/GIF count and whether they have alt text, badge count, LICENSE/CONTRIBUTING/CI presence, last-commit recency) into JSON so you're not eyeballing line counts by hand. If there's no local checkout, do the equivalent checks manually from what you fetched and say which ones you skipped.

2. Score it

Score the five categories in references/scoring-rubric.md (clarity, visual proof, instant trial, trust signals, launch readiness). Give the user the total plus a short, prioritized fix list — ranked by (impact on a first-time visitor) ÷ (effort to fix), not by category order. Nobody wants 40 nitpicks; they want to know what to fix first. Three to seven items is usually right.

Be honest about a low score. A project with great code and a 3/25 first impression is a common, fixable situation, not a failure — say that plainly.

3. Rewrite the README

Don't hand back generic advice — write the actual replacement. Follow the structure and reasoning in references/readme-patterns.md, but adapt it to what the project really is; a CLI tool, a library, and a web app earn different README shapes. Ground every claim in what you actually saw in the code/docs — if you're not sure a feature exists, ask instead of asserting it. Use assets/readme-template.md as a starting skeleton to fill in, not as a rigid mold.

If the repo has no demo screenshot or GIF, say this is usually the single highest-leverage fix (visual proof is what makes someone trust a repo enough to read further) and tell the user concretely what to capture (a terminal recording of the one command that shows the payoff; a before/after; a 15-second GIF beats a wall of text) rather than just noting "add a screenshot."

4. Draft launch copy (when asked, or when the user is clearly about to publish)

Use references/launch-post-patterns.md for Show HN, relevant subreddits, and X/Twitter threads. Each platform has a different tolerance for self-promotion and a different thing it rewards — don't reuse one post across all three. Write posts as the user, in first person, about what they actually built and why; never invent a backstory.

5. Leave a launch checklist

Close with a short, concrete checklist covering the parts people forget: repo description filled in, topics/tags added (these are how GitHub's discovery surfaces work), a social-preview image set, the license visible, and when to post (a Tuesday–Thursday morning in the target community's main timezone consistently outperforms weekend posts for HN/Reddit).

Output format

Default to producing, as applicable to what the user asked for:

1. A short scored summary (category scores + total, 2-4 lines).
2. A prioritized fix list.
3. A complete rewritten README.md (as a file, not just a snippet), if the repo has enough content to write one honestly.
4. Launch post drafts, only if requested or the user says they're about to publish.

Don't pad the response with generic startup-advice filler ("build in public!", "engage with your community!") — every recommendation should trace back to something specific you saw in this repo.