git:20260509.b2d3e98 to git:20260921.a2e8de7

- 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 directory

- - `github-audit <owner/repo>` -- Audit a specific remote repo

- - `github-audit <username>` -- Audit entire portfolio (all public repos)

-

- ## Headless Scope

-

- The deterministic script entrypoint currently covers local repo audits only:

-

- ```bash

- 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:**

-

- ```bash

- # 1. Repo metadata (use repositoryTopics, not topics)

- 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

-

- # 2. Recent activity

- gh api repos/{owner}/{repo}/commits --jq '.[0].commit.committer.date' 2>/dev/null

-

- # 3. Releases (with titles and dates)

- gh release list --repo {owner}/{repo} --limit 5

-

- # 4. README -- read the FULL content, not just check existence

- gh api repos/{owner}/{repo}/readme --jq '.content' | base64 -d

-

- # 5. Community files -- check EACH ONE individually

- # Root-level files:

- 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

-

- # 6. .github directory contents (top level)

- gh api repos/{owner}/{repo}/contents/.github --jq '.[].name' 2>/dev/null

-

- # 7. Issue templates listing

- gh api repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE --jq '.[].name' 2>/dev/null

-

- # 8. PR template check

- gh api repos/{owner}/{repo}/contents/.github/PULL_REQUEST_TEMPLATE.md --jq '.name' 2>/dev/null

-

- # 9. Workflows listing (for CI detection)

- gh api repos/{owner}/{repo}/contents/.github/workflows --jq '.[].name' 2>/dev/null

-

- # 10. Devcontainer check

- gh api repos/{owner}/{repo}/contents/.devcontainer/devcontainer.json --jq '.name' 2>/dev/null

-

- # 11. Dependabot check

- gh api repos/{owner}/{repo}/contents/.github/dependabot.yml --jq '.name' 2>/dev/null

-

- # 12. Release config check

- gh api repos/{owner}/{repo}/contents/.github/release.yml --jq '.name' 2>/dev/null

-

- # 13. Funding check

- gh api repos/{owner}/{repo}/contents/.github/FUNDING.yml --jq '.name' 2>/dev/null

-

- # 14. SECURITY.md content (for legal agent quality assessment)

- gh api repos/{owner}/{repo}/contents/SECURITY.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null

-

- # 15. CITATION.cff content (for legal agent validation)

- gh api repos/{owner}/{repo}/contents/CITATION.cff --jq '.content' 2>/dev/null | base64 -d 2>/dev/null

-

- # 16. CHANGELOG.md first 50 lines (for releases agent)

- gh api repos/{owner}/{repo}/contents/CHANGELOG.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null | head -50

-

- # 17. CONTRIBUTING.md content (for community agent quality assessment)

- gh api repos/{owner}/{repo}/contents/CONTRIBUTING.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null

-

- # 18. PR template content (for community agent quality assessment)

- gh api repos/{owner}/{repo}/contents/.github/PULL_REQUEST_TEMPLATE.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null

-

- # 19. LICENSE file content -- first 20 lines (for legal agent copyright verification)

- gh api repos/{owner}/{repo}/contents/LICENSE --jq '.content' 2>/dev/null | base64 -d 2>/dev/null | head -20

- # Fallback: try LICENSE.md if LICENSE not found

- gh api repos/{owner}/{repo}/contents/LICENSE.md --jq '.content' 2>/dev/null | base64 -d 2>/dev/null | head -20

-

- # 20. config.yml content from ISSUE_TEMPLATE (for community agent blank-issue check)

- gh api repos/{owner}/{repo}/contents/.github/ISSUE_TEMPLATE/config.yml --jq '.content' 2>/dev/null | base64 -d 2>/dev/null

-

- # 21. Image files in assets/ and root (for image format optimization check)

- 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:**

- ```bash

- # Use repositoryTopics (not topics) -- topics field does not exist

- 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.

-

- ```bash

- 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:

- 1. Gather full data (README content + all 16 file checks from Gather step)

- 2. Spawn all 6 agents in parallel (same as single-repo audit)

- 3. **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.

- ```