thatrebeccarae/claude-marketing / skills/repo-health
repo-health
VerifiedOne-command GitHub repository health audit. Checks for missing standard files, GitHub configuration, branch protection, documentation quality, and code hygiene. Produces a scored health report with prioritized fix recommendations.
| File | Kind | Size |
|---|---|---|
| EXAMPLES.md | markdown | 7.3 KB |
| LICENSE | other | 1.0 KB |
| REFERENCE.md | markdown | 9.0 KB |
| SKILL.md | skill md | 9.5 KB |
EXAMPLES.md
View on GitHub# 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |