Repo Health

Repo Health

One-command health audit for GitHub repositories. Produces a scored report with prioritized fix recommendations.

Install

claude skill add --from https://github.com/thatrebeccarae/claude-marketing/skills/repo-health

When to Use

• Setting up a new repo and want to make sure nothing is missing
• Periodic health checks on active repositories
• Before open-sourcing a private repo (what needs to be added?)
• Onboarding onto an unfamiliar repo to assess its state
• Pre-release hygiene sweep

How to Use

/repo-health [repo-path]        # Full audit with scored report
/repo-health [repo-path] --fix  # Audit + generate missing files

Default repo-path is the current working directory if omitted.

Procedure

Execute each step in order. Do not skip steps.

Step 1: Validate Repo Path

1. If repo-path is provided, resolve to absolute path. If omitted, use current working directory.
2. Confirm the path exists and is a directory.
3. Confirm it contains a .git directory (is a git repo).

If validation fails:

Error: {repo-path} is not a git repository.
Provide a path to a git repo or run from within one.

STOP.

Step 2: Detect Public/Private

Determine repo visibility:

1. Check for .public-repo marker file at repo root -> public
2. Check if "public" appears in the remote URL -> public
3. Run gh repo view --json isPrivate -q '.isPrivate' if gh is available -> use result
4. If none of the above resolve it -> ask the user

Store as repo_visibility (public or private). Public repos are held to a stricter standard in scoring.

Step 3: File Presence Checks

Check for each standard file. Track result as PRESENT or MISSING.

Step 4: GitHub Configuration Checks

Use gh CLI to query repo metadata. If gh is not available, skip this category and note it in the report.

gh repo view --json description,repositoryTopics,hasWikiEnabled,defaultBranchRef,homepageUrl

Check each item. Track as PASS or FAIL.

Step 5: Documentation Quality

README checks:

1. README.md exists (from Step 3)
2. README length: < 50 lines = WARN (too short), > 500 lines = INFO (consider splitting)
3. Has a project description in the first 5 lines (H1 or bold text)
4. Has install/setup instructions (scan for "install", "getting started", "setup", "usage")
5. Has a license reference (scan for "license", "LICENSE")
6. If the /github-readme skill is available, note that a deeper README audit can be run via /github:readme audit

CHANGELOG checks:

1. CHANGELOG.md exists (from Step 3)
2. If present: follows Keep a Changelog format (scan for ## [ version headers)
3. Most recent entry is within the last 90 days (WARN if stale)

Step 6: Code Hygiene

Stale branches:

git branch -r --merged main | grep -v main | grep -v HEAD
git for-each-ref --sort=committerdate --format='%(refname:short) %(committerdate:relative)' refs/remotes/

• Flag branches with no commits in > 90 days as stale
• Count total stale branches

Tracked secrets/env files:

git ls-files | grep -E '\.env$|\.env\.|credentials|secrets'

• Any .env, .env.*, credentials.*, or secrets.* files tracked in git = FAIL

Large binary files:

git ls-files | while read f; do
  size=$(wc -c < "$f" 2>/dev/null)
  [ "$size" -gt 5242880 ] && echo "$f ($size bytes)"
done

• Files > 5MB tracked in git without Git LFS = WARN
• Check for .gitattributes with LFS patterns if large binaries exist

Dependency freshness (if applicable):

• If package.json exists: check for package-lock.json presence
• If requirements.txt exists: check if pinned (versions specified)
• Do NOT run install commands or modify anything

Step 7: Score and Report

Scoring Categories

Per-Category Scoring

Each category scores 0-100 based on checks passed within it. See REFERENCE.md for the full rubric.

Letter Grade

Report Format

=== Repo Health Report: {repo-name} ===
Visibility: {public | private}
Overall Score: {score}/100 (Grade: {letter})

--- Standard Files (30%) --- Score: {n}/100
  [PASS] .gitignore
  [PASS] LICENSE (MIT)
  [MISS] SECURITY.md
  [MISS] CONTRIBUTING.md
  [PASS] CODEOWNERS
  ...

--- GitHub Config (15%) --- Score: {n}/100
  [PASS] Description: "One-command repo health audit..."
  [FAIL] Topics: none set
  [PASS] Default branch: main
  [FAIL] Branch protection: not enabled
  ...

--- Documentation (25%) --- Score: {n}/100
  [PASS] README.md (142 lines)
  [WARN] No install/setup instructions found in README
  [MISS] CHANGELOG.md
  ...

--- Code Hygiene (20%) --- Score: {n}/100
  [PASS] No tracked .env files
  [WARN] 3 stale branches (>90 days)
  [PASS] No large binary files tracked
  ...

--- Community (10%) --- Score: {n}/100
  [MISS] CODE_OF_CONDUCT.md
  [MISS] Issue templates
  [PASS] PR template
  ...

=== Prioritized Fixes ===
1. [HIGH] Add SECURITY.md — required for public repos. See template in REFERENCE.md.
2. [HIGH] Enable branch protection on main — prevents force pushes and requires reviews.
3. [HIGH] Add repository topics — improves discoverability. Suggest: {topic1}, {topic2}, {topic3}.
4. [MED]  Add CONTRIBUTING.md — guides external contributors.
5. [MED]  Add CHANGELOG.md — tracks releases for users.
6. [LOW]  Clean up 3 stale branches.
7. [LOW]  Add CODE_OF_CONDUCT.md — signals welcoming community.

Priority levels:

• HIGH: Security, legal (LICENSE/SECURITY.md), or protection issues
• MED: Documentation and community gaps that affect usability
• LOW: Cleanup and nice-to-haves

Step 8: Fix Mode (--fix)

If --fix flag was passed:

1. Present the list of MISS and FAIL items that can be auto-generated
2. Ask the user to confirm which files to create (show numbered list, accept comma-separated selection or "all")
3. For each confirmed file, generate it using sensible defaults:
   • SECURITY.md: Standard vulnerability reporting template
   • CONTRIBUTING.md: Fork/branch/PR workflow with code style notes
   • CODE_OF_CONDUCT.md: Contributor Covenant v2.1
   • .editorconfig: Sensible defaults for the detected tech stack
   • CODEOWNERS: Prompt user for owner patterns
   • Issue/PR templates: YAML form-based templates (see REFERENCE.md)
4. Do NOT overwrite existing files
5. Run infra/PII scrub on all generated content before writing

Key Principles

• Read-only by default. The audit never modifies files unless --fix is explicitly passed.
• Public repos are held to a higher standard. Private repos skip community and some config checks.
• Prioritize actionable output. Every finding includes a specific fix recommendation.
• No false urgency. Recommended items are scored lower than required items. The report distinguishes between must-fix and nice-to-have.
• Respect existing work. Fix mode never overwrites. It only creates missing files.
• Infra/PII awareness. All generated files pass through the standard PII scrub before writing.

Anti-Patterns -- Do NOT

• Modify any files during a standard audit (no --fix flag)
• Run install commands (npm install, pip install, etc.)
• Push changes or create commits -- the user decides when to commit
• Fabricate repository metadata -- use what gh and git report
• Rate repos you do not have local access to -- this is a local audit tool
• Skip the PII scrub when generating files in fix mode