| name | github-audit |
| description | GitHub repo health audit with 0-100 scoring across README, metadata, legal, community, releases, SEO. Single, remote, or portfolio mode. |
GitHub Audit -- Repository Health Scoring
Primary data-gathering skill. Produces the richest dataset that other skills consume.
Modes
github-audit -- Audit the repo in the current directorygithub-audit <owner/repo> -- Audit a specific remote repogithub-audit <username> -- Audit entire portfolio (all public repos)
Headless Scope
The deterministic script entrypoint currently covers local repo audits only:
python3 scripts/run_headless.py audit --path /path/to/repo
Remote repo audits and portfolio audits remain conversational skill flows for
now. Do not imply the headless runner supports them unless that script contract
has been extended.
Process (GARE Pattern)
1. Gather (Comprehensive Data Collection)
Step 0 -- Check shared data cache:
Before running a full audit, check .github-audit/audit-data.json.
Reference: github/references/shared-data-cache.md for schemas.
- If
audit-data.json exists and is from today: offer the user a choice --
"Cached audit scores found from earlier today. Reuse them or re-run fresh?"
If the user says reuse, skip to Step 3 (Recommend) with cached scores.
- If
repo-context.json exists: use it for repo type, intent, language instead
of re-querying gh repo view.
- If cache is stale or user says "re-run" / "refresh": proceed with full gather below.
This step collects ALL data before any analysis. Be thorough -- agents cannot
make their own API calls, so they depend entirely on the data you provide here.
For local/specific repo, run ALL of these:
gh repo view {owner}/{repo} --json name,description,url,homepageUrl,repositoryTopics,visibility,defaultBranchRef,licenseInfo,stargazerCount,forkCount,watchers,primaryLanguage,createdAt,updatedAt,isArchived,isFork,parent,hasIssuesEnabled,hasWikiEnabled,hasDiscussionsEnabled,isSecurityPolicyEnabled,usesCustomOpenGraphImage
gh api repos/{owner}/{repo}/commits --jq '.[0].commit.committer.date' 2>/dev/null
gh release list --repo {owner}/{repo} --limit 5
gh api repos/{owner}/{repo}/readme --jq '.content' | base64 -d
gh api repos/{owner}/{repo}/contents/CONTRIBUTING.md --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/CODE_OF_CONDUCT.md --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/SECURITY.md --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/CITATION.cff --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/CODEOWNERS --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/CHANGELOG.md --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/.gitattributes --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/SUPPORT.md --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/.github --jq '.[].name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE --jq '.[].name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/.github/PULL_REQUEST_TEMPLATE.md --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/.github/workflows --jq '.[].name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/.devcontainer/devcontainer.json --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/.github/dependabot.yml --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/.github/release.yml --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/.github/FUNDING.yml --jq '.name' 2>/dev/null
gh api repos/{owner}/{repo}/contents/SECURITY.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null
gh api repos/{owner}/{repo}/contents/CITATION.cff --jq '.content' 2>/dev/null | base64 -d 2>/dev/null
gh api repos/{owner}/{repo}/contents/CHANGELOG.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null | head -50
gh api repos/{owner}/{repo}/contents/CONTRIBUTING.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null
gh api repos/{owner}/{repo}/contents/.github/PULL_REQUEST_TEMPLATE.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null
gh api repos/{owner}/{repo}/contents/LICENSE --jq '.content' 2>/dev/null | base64 -d 2>/dev/null | head -20
gh api repos/{owner}/{repo}/contents/LICENSE.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null | head -20
gh api repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE/config.yml --jq '.content' 2>/dev/null | base64 -d 2>/dev/null
gh api repos/{owner}/{repo}/contents/assets --jq '.[] | select(.name | test("\\.(png|jpg|jpeg|gif|webp|svg)$"; "i")) | "\(.name) \(.size)"' 2>/dev/null
Optimization: You can run many of these checks in parallel using multiple
Bash tool calls in a single message. Group them logically:
- Group A: metadata + commits + releases + README (the big 4)
- Group B: all community file existence checks (batch into 2-3 commands)
- Group C: .github directory + templates + workflows
- Group D: file contents (SECURITY.md, CITATION.cff, CHANGELOG.md, CONTRIBUTING.md, PR template, LICENSE, config.yml)
For portfolio audit:
gh repo list {username} --visibility public --limit 500 \
--json name,description,repositoryTopics,stargazerCount,forkCount,primaryLanguage,updatedAt,licenseInfo,isArchived,isFork,homepageUrl,url,hasIssuesEnabled,hasDiscussionsEnabled,isSecurityPolicyEnabled,pushedAt,latestRelease
Important: Save ALL gathered data -- you will pass it to agents in Step 2.
2. Analyze (Run 6 Parallel Review Agents)
Use the fastest parallel agent primitive available in the host runtime. Do NOT
score categories yourself inline when agent delegation is available -- the category
reviewers have detailed point-by-point rubrics and load reference files for deep
domain analysis.
- Claude Code: use the Agent tool and spawn all 6 category subagents in one message.
- Codex: use multi-agent delegation /
spawn_agent for all 6 category reviewers in one round.
- No agent primitive available: run the same six rubrics sequentially and say parallel review was unavailable.
Launch all 6 reviewers in parallel. Each reviewer gets the same gathered data,
uses its own rubric, and returns only its category score, findings, and action
items. Wait for all six to finish before aggregating.
| Reviewer | Category | Weight |
|---|
github-readme | README Quality | 25% |
github-meta | Metadata & Discovery | 20% |
github-legal | Legal Compliance | 15% |
github-community | Community Health | 15% |
github-release | Release & Maintenance | 15% |
github-seo | SEO & Discoverability | 10% |
Claude Code invocation pattern for EACH reviewer:
Agent tool call:
subagent_type: "github-readme" <- use the agent name from the table above
description: "Score {repo} README"
prompt: <the data payload below>
Codex invocation pattern for EACH reviewer:
spawn_agent:
agent_type: "github-readme"
message: <the data payload below>
If custom github-* agent types are not exposed in the current Codex runtime,
spawn default workers with an explicit category assignment and tell each worker
which rubric/reference file to apply.
Data payload template (same for all 6 agents):
Score this GitHub repository. Use your rubric and load your reference file.
All data is provided below -- do NOT attempt to fetch anything yourself.
Repository: {owner}/{repo}
Description: {description}
Topics: {topics list}
Primary Language: {language}
License: {license key} -- recognized by GitHub: {yes/no}
Stars: {count} | Forks: {count}
Is Fork: {yes/no} | Parent: {parent if fork}
Homepage URL: {url or "not set"}
Has Issues: {yes/no} | Has Wiki: {yes/no} | Has Discussions: {yes/no}
Security Policy Enabled (GitHub flag): {yes/no}
Custom Social Preview: {yes/no}
Is Archived: {yes/no}
Created: {date} | Last Push: {date} | Last Commit: {date}
Releases:
{list of recent releases with version, title, date -- or "none"}
Community Files Found: {list of all files confirmed to exist}
Community Files Missing: {list of all files confirmed NOT to exist}
.github/ Contents: {list of items in .github/ directory}
Issue Templates: {list of files in .github/ISSUE_TEMPLATE/ or "none/directory not found"}
PR Template: {exists/not found}
CI Workflows: {list of .yml files in .github/workflows/ or "none/directory not found"}
Devcontainer: {exists/not found}
Dependabot: {configured/not found}
Release Config: {configured/not found}
Funding: {configured/not found}
SECURITY.md Content:
{full content or "FILE NOT FOUND" if the API returned 404}
CITATION.cff Content:
{full content or "FILE NOT FOUND" if the API returned 404}
CHANGELOG.md (first 50 lines):
{content or "FILE NOT FOUND" if the API returned 404}
CONTRIBUTING.md Content:
{full content or "FILE NOT FOUND" if the API returned 404}
PR Template Content:
{full content or "FILE NOT FOUND" if the API returned 404}
LICENSE (first 20 lines):
{first 20 lines of LICENSE or LICENSE.md, or "FILE NOT FOUND"}
Issue Template config.yml Content:
{full content or "FILE NOT FOUND" if the API returned 404}
README Content:
{FULL README text -- paste the entire decoded content, or "FILE NOT FOUND"}
Image Files (assets/):
{list of image files with name and size in bytes, or "no assets/ directory" or "no images found"}
--- DATA QUALITY NOTES ---
- "FILE NOT FOUND" means the API confirmed the file does not exist (404).
- Files in "Community Files Found" were confirmed via API to exist.
- Files in "Community Files Missing" were confirmed via API to NOT exist.
- Agents: treat "FILE NOT FOUND" as definitive absence. Score 0 for that file.
Critical rules:
- NEVER summarize or abbreviate the README. Paste the ENTIRE decoded content
verbatim into every agent's payload. Agents cannot score what they cannot see.
Even if the README is 500+ lines, pass it in full. Summarizing causes agents to
score stub content and produces artificially low scores.
- Pass the FULL README content to every agent (especially readme, seo, meta)
- Prefer the named
github-* reviewer type when the runtime exposes it.
- Start all 6 reviewers before waiting on any one reviewer.
- Each reviewer loads its own reference file and applies its own rubric.
- Each reviewer returns: score (0-100), point breakdown table, findings, prioritized issues.
- Reviewers do NOT have Bash access unless the host explicitly provides it. They CANNOT fetch data themselves.
2b. Write to Shared Data Cache
After all 6 agents return, write results to .github-audit/audit-data.json.
Reference: github/references/shared-data-cache.md for schema.
mkdir -p .github-audit
grep -qxF '.github-audit/' .gitignore 2>/dev/null || echo '.github-audit/' >> .gitignore
Write audit-data.json with: timestamp, overall_score, per-category scores,
action_items array, and file_existence map (boolean for each community/legal file).
This cache is consumed by github-empire and optionally by github-readme.
3. Recommend (Aggregate and Prioritize)
IMPORTANT: Wait for ALL 6 agents to return before compiling the report.
Do NOT estimate scores for agents that haven't returned yet. Do NOT compile a
partial report. If running agents in background, wait for every single one to
complete before proceeding to this step. NEVER use estimated scores.
Overall Score: Weighted average of all 6 category scores.
Score Interpretation:
| Range | Rating | Meaning |
|---|
| 90-100 | Excellent | Best-in-class GitHub presence |
| 75-89 | Good | Well-maintained, minor improvements possible |
| 50-74 | Needs Work | Significant gaps in presentation or compliance |
| 25-49 | Poor | Major issues affecting discoverability and trust |
| 0-24 | Critical | Repo appears abandoned or unprofessional |
Priority ranking of action items:
- Critical -- Legal risk or completely missing essentials (no license, no README)
- High -- Significant impact on discoverability (empty description, zero topics)
- Medium -- Optimization opportunity (README could be better structured)
- Low -- Nice to have (add more badges, tweak topic selection)
4. Execute (Standard Operating Procedure)
After presenting the audit report, generate a numbered SOP that tells the user
exactly which skills to run and in what order. This is not a menu -- it is a step-by-step
remediation plan. The order matters because later skills depend on earlier ones.
Canonical skill order (always this sequence):
| Step | Skill | Why This Order |
|---|
| 1 | github-legal | Foundation -- license, compliance, fork obligations must be correct before anything else |
| 2 | github-community | Infrastructure -- templates, CoC, devcontainer build on legal foundation |
| 3 | github-release | Versioning -- CHANGELOG, badges, releases need legal + community in place |
| 4 | github-seo | Research -- keyword data feeds into meta descriptions and README content |
| 5 | github-meta | Settings -- description, topics, features use SEO keyword data |
| 6 | github-readme | Capstone -- the README references everything above and uses SEO keywords |
| 7 | Re-run github-audit | Measure improvement and verify all fixes landed |
SOP generation rules:
- Only include skills where the score is below 90. If legal scored 95, skip it.
- Show the current score next to each skill so the user sees the priority.
- Show a brief reason why that skill needs to run (from the action items).
- Always end with Step 7: re-audit. Even if only one skill ran, measure the delta.
- Number the steps sequentially (1, 2, 3...) skipping skills that scored 90+.
Output format for the SOP (append this AFTER the Action Items section):
### Recommended Next Steps (run in order)
| Step | Command | Current Score | What It Fixes |
|------|---------|---------------|---------------|
| 1 | `github-legal` | 67/100 | Fork copyright, missing CITATION.cff |
| 2 | `github-community` | 52/100 | Missing CODE_OF_CONDUCT, no dependabot |
| 3 | `github-release` | 56/100 | Catch-up releases, missing badges |
| 4 | `github-seo` | 56/100 | Keyword research for description + README |
| 5 | `github-meta` | 67/100 | Topics, settings, social preview |
| 6 | `github-readme` | 52/100 | Full README optimization with SEO keywords |
| 7 | `github-audit` | -- | Re-audit to measure improvement |
Start with Step 1 when ready. Each skill will guide you through its changes
and hand off to the next step.
Once you've completed this SOP for all your repos, run:
github-empire -- portfolio-level optimization (profile README, cross-linking, topic sync)
After presenting the SOP, wait for the user. Do not auto-run any skill.
The user decides when to start and which step to run. If they say "go" or
"start" or "let's do it", run Step 1.
Empire note: The github-empire skill is NOT part of the per-repo SOP.
It operates at the portfolio level (profile README, cross-linking, branding,
avatar). Run it once after you've completed the SOP on all repos you want to
optimize. The audit's SOP output includes this reminder at the bottom.
Scoring Rubrics (Per Category)
README Quality (25%)
| Score | Criteria |
|---|
| 90-100 | H1 with keyword, badges, ToC, installation, usage with examples, proper hierarchy |
| 70-89 | Most sections present, decent structure, minor keyword gaps |
| 50-69 | Basic README exists but missing key sections or poorly structured |
| 25-49 | Minimal README (just project name or one paragraph) |
| 0-24 | No README or empty README |
Metadata & Discovery (20%)
| Score | Criteria |
|---|
| 90-100 | Keyword-rich description, 10-20 topics, homepage URL set, custom social preview |
| 70-89 | Good description, 5-9 topics, homepage URL |
| 50-69 | Basic description, 1-4 topics |
| 25-49 | Description exists but generic, zero topics |
| 0-24 | No description, no topics |
Legal Compliance (15%)
| Score | Criteria |
|---|
| 90-100 | Correct license, SECURITY.md, CITATION.cff, fork compliance (if fork) |
| 70-89 | License present and correct, one of SECURITY/CITATION |
| 50-69 | License present but may not match intent |
| 25-49 | License file exists but not recognized by GitHub |
| 0-24 | No license (legally "all rights reserved") |
Community Health (15%)
| Score | Criteria |
|---|
| 90-100 | Full Community Standards green, YAML issue forms, PR template, devcontainer |
| 70-89 | Most community files present, at least basic templates |
| 50-69 | CONTRIBUTING and CoC present, basic issue template |
| 25-49 | Only one or two community files |
| 0-24 | No community files at all |
Release & Maintenance (15%)
| Score | Criteria |
|---|
| 90-100 | Regular semver releases, CHANGELOG, CI badges, Dependabot, recent activity |
| 70-89 | Releases exist, basic changelog or auto-notes, CI present |
| 50-69 | Some releases, no changelog, CI status unclear |
| 25-49 | No releases, but recent commits |
| 0-24 | No releases, no recent activity (stale) |
SEO & Discoverability (10%)
| Score | Criteria |
|---|
| 90-100 | Keywords in README H1, optimized description, Pages site, Discussions enabled |
| 70-89 | Good keyword presence, adequate description, some discovery features |
| 50-69 | Basic keyword presence, room for optimization |
| 25-49 | No keyword strategy, generic content |
| 0-24 | Actively harmful (misleading description, wrong topics) |
Portfolio Audit Mode
For github-audit <username>:
Step 0: Filter Out Noise
After fetching the repo list, immediately exclude repos that aren't worth
auditing. These get listed in a "Skipped" section but consume zero tokens:
- Archived repos -- frozen, not actionable
- Bare forks with zero commits ahead -- just a mirror, nothing to optimize
- Repos with no description AND no README AND last push > 2 years ago -- dead repos
Report how many were filtered:
Found {N} public repos for {username}.
Filtered out {F} repos (archived, bare forks, abandoned).
{N-F} active repos to evaluate.
Step 1: Quick Scan (all active repos, no agents)
Gather metadata for ALL active repos via gh repo list. For each repo, do a
lightweight inline score based on metadata alone (description, topics, license,
releases, last push date). This produces a rough ranking. Quick-scan is cheap --
it uses only the data from the single gh repo list call.
Step 2: Select Deep Dives
Pick which repos get the full 6-agent treatment:
| Active Repos | Deep Dive Selection | Max Agents |
|---|
| 1-9 | ALL repos | 54 |
| 10-30 | Top 3 + worst 5 by quick-scan score | 48 |
| 31-100 | Top 3 + worst 7 | 60 |
| 100+ | Top 3 + worst 7 + highest-starred 2 (if not already selected) | 72 |
Hard cap: Never deep-dive more than 12 repos (= 72 agents max).
Prioritize wisely for deep dives:
- "Top" = highest quick-scan score (these are your showcase repos -- worth polishing)
- "Worst" = lowest quick-scan score AMONG repos that are still worth saving
(skip repos with zero stars, zero forks, and last push > 1 year ago --
they're probably experiments the user forgot about)
- "Highest-starred" = repos with the most community visibility (most to gain)
Step 3: Confirmation
Before spawning any agents, show the plan:
Portfolio: {username} ({N-F} active repos, {F} skipped)
Deep-diving {M} repos (6 agents each = {M*6} total):
- repo-a (stars: 42, quick score: 78) -- top repo
- repo-b (stars: 15, quick score: 71) -- top repo
- repo-c (stars: 8, quick score: 65) -- top repo
- repo-d (stars: 0, quick score: 22) -- needs work
- repo-e (stars: 1, quick score: 18) -- needs work
...
Remaining {N-F-M} repos get quick-scan estimated scores.
Proceed? [Y/n]
Step 4: Deep Dive (WITH agents)
For each selected repo:
- Gather full data (README content + all 16 file checks from Gather step)
- Spawn all 6 agents in parallel (same as single-repo audit)
- Wait for ALL agents to complete before compiling any report
Portfolio Report Includes
- Per-repo scores (sorted by score, ascending)
- Skipped repos summary (with reason for each)
- Portfolio average score (active repos only)
- Consistency check (description style, topic overlap, badge usage)
- Topic coverage analysis (niche authority gaps)
- Top 3 repos to prioritize improving
- Cross-repo patterns (common issues)
Output Format
## GitHub Audit Report: {repo-name}
### Overall Score: XX/100 ({rating})
| Category | Score | Weight | Weighted |
|----------|-------|--------|----------|
| README Quality | XX/100 | 25% | XX |
| Metadata & Discovery | XX/100 | 20% | XX |
| Legal Compliance | XX/100 | 15% | XX |
| Community Health | XX/100 | 15% | XX |
| Release & Maintenance | XX/100 | 15% | XX |
| SEO & Discoverability | XX/100 | 10% | XX |
### Action Items
#### Critical
- [item with specific fix]
#### High
- [item with specific fix]
#### Medium
- [item with specific fix]
#### Low
- [item with specific fix]
### Recommended Next Steps (run in order)
| Step | Command | Current Score | What It Fixes |
|------|---------|---------------|---------------|
| 1 | `github-legal` | XX/100 | [specific issues] |
| 2 | `github-community` | XX/100 | [specific issues] |
| 3 | `github-release` | XX/100 | [specific issues] |
| 4 | `github-seo` | XX/100 | [specific issues] |
| 5 | `github-meta` | XX/100 | [specific issues] |
| 6 | `github-readme` | XX/100 | [specific issues] |
| 7 | `github-audit` | -- | Re-audit to measure improvement |
Start with Step 1 when ready. Each skill will guide you through
its changes and hand off to the next step.
