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

Repo Health Examples

Practical examples showing repo-health audit output for different scenarios.

Example 1: New Public Repo (Low Score)

User Request: /repo-health ~/projects/my-new-tool

A freshly created public repo with only source code committed. No standard files, no GitHub configuration.

Output:

=== Repo Health Report: my-new-tool ===
Visibility: public
Overall Score: 22/100 (Grade: F)

--- Standard Files (30%) --- Score: 20/100
  [PASS] .gitignore
  [MISS] LICENSE
  [MISS] SECURITY.md
  [MISS] CONTRIBUTING.md
  [MISS] CODEOWNERS
  [MISS] .editorconfig
  [MISS] .github/pull_request_template.md
  [MISS] .github/ISSUE_TEMPLATE/
  [MISS] CHANGELOG.md
  [MISS] CODE_OF_CONDUCT.md

--- GitHub Config (15%) --- Score: 0/100
  [FAIL] Description: not set
  [FAIL] Topics: none set
  [PASS] Default branch: main
  [FAIL] Branch protection: not enabled

--- Documentation (25%) --- Score: 20/100
  [PASS] README.md (8 lines)
  [WARN] README is a stub (< 10 lines)
  [WARN] No install/setup instructions found
  [WARN] No license reference in README
  [MISS] CHANGELOG.md

--- Code Hygiene (20%) --- Score: 60/100
  [PASS] No tracked .env files
  [PASS] No large binary files tracked
  [WARN] No package-lock.json (package.json exists)
  [PASS] No stale branches

--- Community (10%) --- Score: 0/100
  [MISS] CODE_OF_CONDUCT.md
  [MISS] CONTRIBUTING.md
  [MISS] Issue templates
  [MISS] PR template

=== Prioritized Fixes ===
1. [HIGH] Add LICENSE — legally required for open-source distribution. MIT recommended.
2. [HIGH] Add SECURITY.md — required for public repos accepting contributions.
3. [HIGH] Set repository description — currently empty.
4. [HIGH] Add 3+ repository topics — improves discoverability.
5. [MED]  Expand README.md — add project description, install instructions, usage examples.
6. [MED]  Add CONTRIBUTING.md — guides external contributors on your workflow.
7. [MED]  Enable branch protection on main — prevents accidental force pushes.
8. [MED]  Add CHANGELOG.md — track releases for users.
9. [LOW]  Add .editorconfig — ensures consistent formatting across contributors.
10.[LOW]  Add CODE_OF_CONDUCT.md — signals a welcoming community.
11.[LOW]  Add issue templates — structured bug reports and feature requests.
12.[LOW]  Add PR template — consistent pull request descriptions.
13.[LOW]  Commit package-lock.json — ensures reproducible installs.

Run /repo-health ~/projects/my-new-tool --fix to auto-generate missing files.

Example 2: Mature Public Repo (High Score)

User Request: /repo-health ~/projects/my-agent

A well-maintained public repo with most standard files in place.

Output:

=== Repo Health Report: my-agent ===
Visibility: public
Overall Score: 85/100 (Grade: B)

--- Standard Files (30%) --- Score: 80/100
  [PASS] .gitignore
  [PASS] LICENSE (MIT)
  [PASS] SECURITY.md
  [PASS] CONTRIBUTING.md
  [MISS] CODEOWNERS
  [PASS] .editorconfig
  [PASS] .github/pull_request_template.md
  [PASS] .github/ISSUE_TEMPLATE/ (2 templates)
  [MISS] CHANGELOG.md
  [PASS] CODE_OF_CONDUCT.md

--- GitHub Config (15%) --- Score: 100/100
  [PASS] Description: "Autonomous AI agent with taste, memory, and goals"
  [PASS] Topics: ai-agent, typescript, autonomous, llm (4 topics)
  [PASS] Default branch: main
  [PASS] Branch protection: enabled (1 review required)

--- Documentation (25%) --- Score: 80/100
  [PASS] README.md (187 lines)
  [PASS] Has project description
  [PASS] Has install/setup instructions
  [PASS] Has license reference
  [MISS] CHANGELOG.md
  [WARN] README has no "Why I Built This" section (run /github:readme audit for details)

--- Code Hygiene (20%) --- Score: 80/100
  [PASS] No tracked .env files
  [PASS] No large binary files tracked
  [PASS] package-lock.json present
  [WARN] 2 stale branches: feature/old-plugin (4 months), experiment/v1-api (6 months)

--- Community (10%) --- Score: 100/100
  [PASS] CODE_OF_CONDUCT.md
  [PASS] CONTRIBUTING.md
  [PASS] Issue templates (bug_report.yml, feature_request.yml)
  [PASS] PR template

=== Prioritized Fixes ===
1. [MED]  Add CHANGELOG.md — no changelog found. Start with current version.
2. [MED]  Add CODEOWNERS — auto-assign PR reviewers by file path.
3. [LOW]  Clean up 2 stale branches (feature/old-plugin, experiment/v1-api).

Example 3: Pre-Open-Source Audit (Private to Public)

User Request: /repo-health ~/projects/my-dashboard-dev

Auditing a private repo before making it public. The report highlights everything that needs to be added.

Output:

=== Repo Health Report: my-dashboard-dev ===
Visibility: private
Overall Score: 58/100 (Grade: F)

NOTE: This repo is currently private. Scoring below uses PUBLIC repo
standards since you indicated you are preparing to open-source it.
Re-run without the public flag to see private-only scoring.

--- Standard Files (30%) --- Score: 40/100
  [PASS] .gitignore
  [PASS] README.md
  [MISS] LICENSE — REQUIRED before open-sourcing
  [MISS] SECURITY.md — REQUIRED before open-sourcing
  [MISS] CONTRIBUTING.md
  [MISS] CODEOWNERS
  [PASS] .editorconfig
  [MISS] .github/pull_request_template.md
  [MISS] .github/ISSUE_TEMPLATE/
  [MISS] CHANGELOG.md
  [MISS] CODE_OF_CONDUCT.md

--- GitHub Config (15%) --- Score: 50/100
  [PASS] Description: "AI-powered project management for Claude Code agents"
  [FAIL] Topics: none set
  [PASS] Default branch: main
  [FAIL] Branch protection: not enabled

--- Documentation (25%) --- Score: 60/100
  [PASS] README.md (94 lines)
  [PASS] Has project description
  [PASS] Has install/setup instructions
  [WARN] No license reference in README (LICENSE file also missing)
  [MISS] CHANGELOG.md

--- Code Hygiene (20%) --- Score: 60/100
  [PASS] No large binary files tracked
  [PASS] package-lock.json present
  [WARN] 5 stale branches (>90 days)
  [FAIL] Tracked .env file: .env.example — review contents before open-sourcing

--- Community (10%) --- Score: 25/100
  [MISS] CODE_OF_CONDUCT.md
  [MISS] CONTRIBUTING.md
  [MISS] Issue templates
  [MISS] PR template

=== Pre-Open-Source Checklist ===

MUST DO before making public:
1. [HIGH] Add LICENSE — cannot open-source without one. MIT recommended.
2. [HIGH] Add SECURITY.md — vulnerability reporting process for contributors.
3. [HIGH] Review .env.example — ensure no real credentials, only placeholder values.
4. [HIGH] Run /safe-push scan — check all commit history for PII, secrets, infra details.
5. [HIGH] Set repository topics — add 3+ for discoverability.

SHOULD DO before making public:
6. [MED]  Add CONTRIBUTING.md — tell contributors how to participate.
7. [MED]  Add CHANGELOG.md — document what shipped in each version.
8. [MED]  Enable branch protection on main — prevent accidental force pushes.
9. [MED]  Add PR template — standardize pull request descriptions.
10.[MED]  Add issue templates — structured bug reports and feature requests.

NICE TO HAVE:
11.[LOW]  Add CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
12.[LOW]  Add CODEOWNERS — auto-assign reviewers.
13.[LOW]  Clean up 5 stale branches before going public.

Run /repo-health ~/projects/my-dashboard-dev --fix to auto-generate missing files.

The pre-open-source audit adds a dedicated checklist section that separates "must do" (legal/security blockers) from "should do" (quality) and "nice to have" (polish). It also flags the need to run /safe-push to scan commit history for leaked secrets before the repo becomes publicly visible.

Repo Health Reference

Technical reference for the repo-health skill. Scoring rubrics, standard file descriptions, API endpoints, and templates.

Standard Files Checklist

GitHub API Endpoints

These are used via gh api to check repo configuration.

Repo Metadata

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

Returns: description (string), repositoryTopics (array of {name}), defaultBranchRef.name (string), homepageUrl (string).

Branch Protection

gh api repos/{owner}/{repo}/branches/main/protection

Returns 200 if protection is enabled, 404 if not. Requires admin access to read.

Repository Details (Social Preview)

gh api repos/{owner}/{repo} --jq '.has_pages, .open_issues_count, .has_projects'

Topics (Set)

gh repo edit --add-topic "topic1" --add-topic "topic2"

Description (Set)

gh repo edit --description "Your description here"

Scoring Rubric

Standard Files (30% weight)

For private repos: only README.md and .gitignore are scored. All others are informational.

GitHub Config (15% weight)

Documentation (25% weight)

Code Hygiene (20% weight)

Community (10% weight)

Branch Protection Recommended Settings

For public repos, recommend these settings via gh api:

{
  "required_status_checks": {
    "strict": true,
    "contexts": []
  },
  "enforce_admins": false,
  "required_pull_request_reviews": {
    "required_approving_review_count": 1,
    "dismiss_stale_reviews": true
  },
  "restrictions": null,
  "allow_force_pushes": false,
  "allow_deletions": false
}

Key settings explained:

• Require PR reviews (1+): Prevents direct pushes to main
• Dismiss stale reviews: Re-request review when new commits are pushed
• No force pushes: Protects commit history
• No branch deletion: Prevents accidental deletion of main
• Strict status checks: Branch must be up to date before merging

For solo developers, a lighter config is acceptable:

• Require PR reviews: 0 (self-merge is fine)
• No force pushes: enabled
• No branch deletion: enabled
• Status checks: optional

Issue Template Format (YAML Form-Based)

Bug Report: .github/ISSUE_TEMPLATE/bug_report.yml

name: Bug Report
description: Report a bug or unexpected behavior
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: "Thanks for reporting a bug. Please fill out the sections below."
  - type: textarea
    id: description
    attributes:
      label: Describe the bug
      description: A clear description of the unexpected behavior.
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      description: How can we reproduce this?
      placeholder: |
        1. Go to '...'
        2. Click on '...'
        3. See error
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Expected behavior
      description: What did you expect to happen?
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      description: What version are you using?
    validations:
      required: false
  - type: textarea
    id: context
    attributes:
      label: Additional context
      description: Any other information (screenshots, logs, environment).
    validations:
      required: false

Feature Request: .github/ISSUE_TEMPLATE/feature_request.yml

name: Feature Request
description: Suggest a new feature or improvement
title: "[Feature]: "
labels: ["enhancement"]
body:
  - type: textarea
    id: problem
    attributes:
      label: Problem or motivation
      description: What problem does this solve? Why do you need it?
    validations:
      required: true
  - type: textarea
    id: solution
    attributes:
      label: Proposed solution
      description: How would you like this to work?
    validations:
      required: true
  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives considered
      description: Any workarounds or alternative approaches you've tried?
    validations:
      required: false

PR Template Format

.github/pull_request_template.md

## Summary

<!-- What does this PR do? Link to related issue(s). -->

## Changes

-

## Testing

- [ ] Tests pass locally
- [ ] Manual testing completed
- [ ] No regressions observed

## Notes

<!-- Anything reviewers should know? -->

Common .gitignore Entries by Language

Node.js / TypeScript

node_modules/
dist/
build/
.env
.env.*
*.log
.DS_Store
coverage/
.turbo/
.next/

Python

__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
.env
.venv/
venv/
.pytest_cache/
.mypy_cache/
*.egg

Rust

target/
Cargo.lock  # for libraries only; commit for binaries
*.pdb

Go

bin/
vendor/  # if using go modules
*.exe
*.test

Universal (always include)

.DS_Store
Thumbs.db
*.swp
*.swo
*~
.idea/
.vscode/
*.env
*.env.*