Audits your GitHub repo's public surface across 5 dimensions, in parallel.
For solo OSS maintainers whose working product is buried under a weak README.
What this isn't: a code linter, a security scanner, or a generic LLM "rewrite my README" prompt. It looks at how your repo is perceived — by humans skimming GitHub, by Google, and by AI engines summarizing your project. Nothing else.
Your README should feel like ripgrep's or bat's — opinionated, scannable, and confident about what it is and isn't. Not like a SaaS landing page.
flowchart LR
A[/github-repo-audit URL/] --> B[Intake: ground truth]
B --> C{5 agents in parallel}
C --> D1[competitive-analyst]
C --> D2[market-researcher]
C --> D3[product-strategist]
C --> D4[ui-ux-designer]
C --> D5[content-marketer]
D1 & D2 & D3 & D4 & D5 --> E[Synthesis]
E --> F[Severity-ranked issue list]
F --> G{Approval gate}
G -->|approved| H[Apply: README + gh repo edit]
G -->|rejected| I[Stop, no writes]
- Intake — you paste a repo URL (or point at a local path) and a one-paragraph "what this product actually is." If you skip that paragraph, the skill drafts one from your README and asks you to confirm.
- Five agents in parallel — each looks at one dimension of your repo's public surface and returns under 800 words.
- You approve, the skill applies — synthesis becomes a severity-ranked issue list (Critical/High/Medium/Low). You pick what to apply. Nothing writes to disk or hits
gh repo editwithout your sign-off.
mkdir -p ~/.claude/skills && \
git clone https://github.com/dancolta/github-repo-audit ~/.claude/skills/github-repo-auditThat's it. The skill is now available as /github-repo-audit (and triggers on phrases like "audit my repo" or "rewrite my readme").
/github-repo-audit https://github.com/yourname/yourproject
Then answer the ground-truth question, watch the 5 agents run in parallel, review the issue list, and approve the fixes you want applied.
The 5 dimensions:
- Competitive landscape — patterns from 5–10 high-star OSS READMEs in your category
- Target-user pain language — verbatim vocabulary from Reddit, HN, X, dev forums
- Product positioning — anti-positioning lines, comparison-table axes, one-sentence pitch
- README visual hierarchy + asset hygiene — above-fold blueprint, hero asset presence and dimensions, badge discipline (max 3), TOC and accordion patterns. Visual design judgment still requires human review.
- SEO + AI-citation surface — GitHub topic tags, Google keyword map, Perplexity/ChatGPT/Claude citation blocks
synthesis.md— combined findings from all 5 agentsissues.md— Critical/High/Medium/Low issues with proposed fixesREADME.md— rewritten in a fixed section ordergithub-metadata.md— About sentence + topic tags + suggested renamehero-shotlist.md— frame-by-frame spec for the hero asset
claude-gif — optional. If installed, the audit offers to render the hero asset shotlist into an actual GIF. The audit works end-to-end without it; you just get the spec instead of the file.
| github-repo-audit | ChatGPT prompt | README generator | Manual rewrite | |
|---|---|---|---|---|
| Audits full public surface (name, About, topics, hero, README) | ✓ | ✗ | ✗ | partial |
| Multi-agent: competitive + market + product + UI/UX + SEO | ✓ | ✗ | ✗ | ✗ |
| Severity-ranked issue list before any edit | ✓ | ✗ | ✗ | ✗ |
| Approval gate before applying fixes | ✓ | ✗ | n/a | n/a |
| Hard rejection of AI-slop phrasing (emoji headers, "unleash", filler) | ✓ | ✗ | ✗ | partial |
Applies fixes via gh repo edit (topics, About, name) |
✓ | ✗ | ✗ | partial |
| Preserves maintainer voice | ✓ | ✗ | partial | ✓ |
| Time to actionable diff | ~5 min | ~30 min of prompting | hours of templating | days–weeks |
Does this skill work on private repos?
Yes. The audit reads the local repo and works offline for the README. The gh repo edit step needs gh auth status to pass; if you're unauthenticated, the skill emits a copy-paste block of the commands instead of running them.
What if the 5 agents disagree?
The orchestrator surfaces a conflict to you only when it's load-bearing — contradictory positioning sentences, category decisions, or rename recommendations. Stylistic differences get merged automatically. You're not asked to arbitrate every micro-disagreement.
Will it overwrite my README without warning?
No. Every file write and every gh mutation requires your explicit approval. The 5 research agents run read-only.
Does it work on monorepos?
It audits the root README. Sub-package READMEs (packages/*/README.md) are out of scope — re-run the skill from inside the package directory if you need those audited.
How is this different from a README generator?
A README generator creates documentation from scratch. github-repo-audit analyzes an existing README and repo surface to find specific positioning, clarity, and discoverability gaps — targeting maintainers who already have a working product but an underselling public presence.
What is a Claude Code skill?
A Claude Code skill is a reusable command file (a Markdown file with embedded instructions) that extends Claude Code's behavior for a specific workflow. github-repo-audit is a skill that acts as an orchestrator, spawning specialist sub-agents to audit a repo's public surface and apply approved improvements.
MIT — see LICENSE.
Built by Dan Colta as a Claude Code skill. Bug reports: issues.