repo-maintainer
Skill4 starsChanged 4 days agoMITView on GitHub
Audits leftover test artifacts, dependencies, CI workflows, docs that have drifted from the code, git hygiene and FAF alignment, then writes a cleanup plan ordered by impact. Use when someone wants a repository cleaned up or checked: "clean up this repo", "audit the repo", "health check before the release". Changes nothing without approval.
- Reads credentials
4 other projects use a version of this.
Adopted by
Most recently taken up by
- freanocank/repo-maintainertheir own version, first seen Oct 25, 2026
- BaoBao1996121/crazy-harnesstheir own version, first seen Oct 20, 2026
- duolahypercho/codex-routertheir own version, first seen Oct 8, 2026
- tzwkb/repo-maintainertheir own version, first seen Jul 18, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- duolahypercho/codex-router★ 4ksame name
- BaoBao1996121/crazy-harness★ 0same name
- freanocank/repo-maintainer★ 0same name
- tzwkb/repo-maintainer★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- faf-contextSkill
- faf-expertSkill
- faf-goSkill
- faf-wizardSkill
- wjttc-builderSkill
- wjttc-testerSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. 0 are common, 13 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
13
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
After major refactoring or before releases
- Distinctive: line 57
Check git status for untracked patterns
- Distinctive: line 89
Remove EOL runtimes (e.g. Node 16) from release workflows
- Distinctive: line 162
After audit, generate prioritized task list:
- Distinctive: line 288
Run checks in order of priority:
- Distinctive: line 296
Create structured report with:
- Distinctive: line 310
Never make changes without explicit approval.
- Distinctive: line 404
When onboarding new devs
- Distinctive: line 408
Document before cleaning (understand why artifacts exist)
- Distinctive: line 409
Test after cleanup (ensure nothing broke)
- Distinctive: line 412
Use TodoWrite for multi-step cleanups
- Distinctive: line 413
Create issues for manual items
- Distinctive: line 414
Document decisions in CLAUDE.md
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- faf:start -->v: 1
needs: [git, "npx (for depcheck and npm outdated)", "faf-cli, for the FAF alignment check"]
reads: [the repository, dependencies, CI workflows, docs, git history]
writes:
- "the health report and the cleanup plan"
- "approved changes only, after an explicit yes"
network: ["registry.npmjs.org (read: depcheck, npm outdated)"]
publishes: false
done_when: "the health report and the cleanup plan, ordered by impact, are written; nothing changed without approval"
project: project.faf<!-- faf:end -->Repo Maintainer - Championship Repository Hygiene
"When brakes must work flawlessly, so must our repos."
When to Use This Skill
Activate when:
- User types
/repo-maintainer - User says "clean up this repo" or "audit the repo"
- Starting maintenance on a repository
- After major refactoring or before releases
- Monthly/quarterly repo health checks
- Onboarding to a new codebase
What This Skill Does
Phase 1: Comprehensive Audit
Systematically checks 7 critical areas:
1. Artifact Detection
# Find test artifacts
*.test.js leftovers
*.spec.ts.snap orphans
.DS_Store files
tmp/, temp/, cache/ directories
coverage/ not in .gitignore
dist/, build/ committed by accident
node_modules/ somehow in gitDetection Strategy:
- Check
git statusfor untracked patterns - Scan for common artifact extensions
- Compare against .gitignore
- Find large files (>1MB) in working directory
2. Dependency Health
# Check package health
npm outdated
npm audit
npx depcheck (find unused deps)
Check for pinned versions (inquirer@8.2.5 pattern)
Verify Dependabot configRed Flags:
- Packages with security vulnerabilities
- EOL runtime versions (Node 16, Python 3.7)
- Duplicate dependencies (lodash + lodash.merge)
- Unused dependencies (installed but never imported)
3. CI/CD Alignment
# Workflow consistency check
Node versions across all workflows
Test matrices (should match across ci.yml, release.yml)
Action versions (@v6 vs @v5)
Failed/skipped workflow runs
Secrets/tokens properly configuredCommon Fixes:
- Remove EOL runtimes (e.g. Node 16) from release workflows
- Align Node versions across all workflows (current LTS lines, e.g. 22/24)
- Pin packages that break under ESM resolution
4. Documentation Sync
# Context alignment check
README.md ↔ CLAUDE.md ↔ project.faf
CHANGELOG up to date with git tags
package.json version matches latest tag
Examples in README still work
Links not broken (404 checks)FAF-Specific:
- project.faf reflects current state
- CLAUDE.md written from project.faf (
faf sync, one way) - .faf-dna not churning unnecessarily
5. Git Hygiene
# .gitignore audit
Untracked files that should be ignored
*.config.mjs
*.faf test artifacts
.env.local, .env.development
Large files in git history (use git-filter-repo)
Binary files that don't belongPattern Recognition:
# Add to .gitignore based on artifacts found
*.faf.backup
.faf-dna.tmp
test-*.faf6. Code Quality Signals
# Quick health indicators
Dead code (unused exports via ts-prune or depcheck)
TODO/FIXME comments (track count, prioritize)
Commented code blocks (remove or document)
Console.log statements in production code
Hardcoded secrets/tokens7. FAF Ecosystem Health
For FAF projects specifically:
# Check FAF alignment
.faf score accuracy (run faf score)
Sync alignment — .faf → CLAUDE.md (run `faf sync`; one way, writes faf's block only)
MCP server compliance (if applicable)
WJTTC test coverage (for faf-cli, MCP servers)For MCP servers:
# MCP-specific checks
package.json has "mcpName" + server.json (MCP Registry)
Server implements required tools
Tests cover all tool endpoints
README has MCP installation instructions
Registry listing accurate (npm + MCP registry)Phase 2: Cleanup Plan Generation
After audit, generate prioritized task list:
# REPO HEALTH REPORT: faf-cli
**Overall Score:** 85% ◇ Bronze
**Status:** Production-ready with minor cleanup needed
---
## CRITICAL (Fix Now)
### 1. Security: `open@10` breaking CI/CD
- **Impact:** Release pipeline failing
- **Fix:** Pin to `open@8.4.2` (fixed)
- **Effort:** 5 minutes
- **Auto-fix:** Available
---
## MEDIUM (This Week)
### 3. .gitignore Gaps
- **Issue:** `*.config.mjs`, `*.faf` test files not ignored
- **Fix:** Add patterns to .gitignore
- **Effort:** 1 minute
- **Auto-fix:** Available
```gitignore
*.config.mjs
test-*.fafLOW (Nice to Have)
6. README Links
- Issue: 2 broken links to old docs
- Fix: Update URLs
- Effort: 5 minutes
7. Unused Dependencies
- Issue:
depcheckfound unused packages - Fix: Remove or document why needed
EXCELLENT
- Test coverage: 799/799 passing
- TypeScript strict mode: enabled
- FAF score: 83% (good)
- CI/CD: All workflows aligned
- Security: No critical vulnerabilities
- Documentation: CLAUDE.md in sync
RECOMMENDED ACTIONS
Quick wins: .gitignore + CHANGELOG entry + README links + a reviewed npm update.
This week: triage TODOs, remove unused deps, bump patch.
Monthly: full dependency audit, large-file scan, perf baseline.
AUTO-FIX AVAILABLE
I can automatically fix:
- ✓ .gitignore additions
- ✓ CHANGELOG draft
- ✓ Safe dependency updates
- ✓ Workflow alignment
Run auto-fix? (yes/no)
---
### **Phase 3: Auto-Fix (Optional)**
For safe, non-breaking fixes:
```bash
# 1. Update .gitignore
cat >> .gitignore <<EOF
# Auto-added by repo-maintainer
*.faf.backup
.faf-dna.tmp
test-*.faf
EOF
# 2. Generate CHANGELOG entry from git log
git log <last-tag>..HEAD --pretty=format:"- %s (%h)" >> CHANGELOG.draft.md # review, then merge into CHANGELOG.md
# 3. Dependency updates — REVIEW REQUIRED: show the diff and run the tests before committing
npm update --save
# 4. Create cleanup branch
git checkout -b repo-maintenance/$(date +%Y-%m-%d)
git add .gitignore CHANGELOG.draft.md package.json package-lock.json
git commit -m "chore: repo maintenance - cleanup artifacts and update deps
- Add missing .gitignore patterns
- Draft CHANGELOG entry since the last tag
- Dependency updates (patch/minor, reviewed and tested)
Generated by /repo-maintainer skill"Workflow
Step 1: Initial Assessment
# Quick health check
pwd
git status
git log --oneline -5
ls -la | head -20Step 2: Systematic Audit
Run checks in order of priority:
- Critical first - CI/CD failures, security issues
- Medium next - Dependencies, documentation gaps
- Low priority - Code quality signals, nice-to-haves
Step 3: Generate Report
Create structured report with:
- Overall health score (0-100%)
- Critical/Medium/Low sections
- Effort estimates
- Auto-fix availability
- Recommended action plan
Step 4: Execute (with approval)
Ask user:
- "Run auto-fix for safe items?"
- "Create cleanup branch?"
- "Open issues for manual items?"
Never make changes without explicit approval.
MCP Server Maintenance
Additional MCP Checks:
# 1. MCP-specific structure
package.json has "mcpName" + server.json (MCP Registry)
Server exports via index.ts
Tools properly registered
# 2. Registry compliance
Registry listing accurate (npm + MCP registry)
README has MCP install instructions
Works with Claude Desktop config
# 3. Tool coverage
Each tool has tests
Each tool has description
Error handling implemented
# 4. Version alignment
package.json version
git tag version
MCP registry version
npm published versionMCP Cleanup Checklist:
- Remove test artifacts
- Update dependencies
- Align workflows (supported Node LTS lines only)
- Verify MCP tools still work
- Update README examples
- Check CHANGELOG current
- Verify published to npm
- Confirm registry listing accurate
✪ Tier System (Aligned with FAF)
CRITICAL: Use Official FAF Tiers for All Scoring
| Score | Tier | Symbol | Status |
| 100% | Trophy | ✪ | AI is optimized to code |
| 99% | Gold | ★ | Exceptional |
| 95% | Silver | ◆ | Top tier |
| 85% | Bronze | ◇ | Production ready |
| 70% | Green | ● | Solid foundation |
| 55% | Yellow | ● | Needs improvement |
| 1% | Red | ○ | Major work needed |
| 0% | White | ♡ | Empty |
The score is deterministic — same input → same score, every time. FAF doesn't lie.
Note: Big Orange is an HONOR, not a score or a badge. It recognizes sustained excellence across multiple criteria; it is never calculated from a single score.
Apply These Tiers to:
- Overall repo health score
- Individual category scores (CI/CD, Dependencies, etc.)
- Summary reports
- Cleanup recommendations
Examples:
95% Security → ◆ Silver
88% Overall → ◇ Bronze
78% Dependencies → ● Green
70% Git Hygiene → ● Green
40% CI/CD → ○ Red
100% Tests → ✪ TrophyRelated Skills
/wjttc-builder·/wjttc-tester- generate + run championship-grade tests before a release/faf-expert- master the.fafformat + score the repo's AI-readiness
Best Practices
1. Run Regularly
- After major refactors
- Before releases
- Monthly maintenance
- When onboarding new devs
2. Prioritize Impact
- Fix breaking issues first (CI/CD, security)
- Document before cleaning (understand why artifacts exist)
- Test after cleanup (ensure nothing broke)
3. Track Progress
- Use TodoWrite for multi-step cleanups
- Create issues for manual items
- Document decisions in CLAUDE.md
4. Automate Where Safe
- .gitignore additions ✓
- CHANGELOG drafts ✓
- Workflow alignment ✓
- Breaking changes ✗ (need review)
Example Session
User: /repo-maintainer
Claude: Starting championship repo maintenance audit...
[Runs git status]
[Checks workflows]
[Scans for artifacts]
[Runs npm outdated]
[Checks .gitignore]
AUDIT COMPLETE
Overall Health: 85% ◇ Bronze
Critical Issues: 2
Medium Issues: 3
Low Priority: 5
Top Issues:
1. [critical] open@10 breaking CI/CD (auto-fixable)
2. [critical] Node 16 in workflows (EOL)
3. [medium] .gitignore missing *.faf.backup
4. [medium] 15 outdated dependencies
5. [medium] CHANGELOG missing v4.4.0
I can auto-fix items 1, 2, 3, and draft 5.
Would you like me to proceed? (yes/no)
User: yes
Claude: Fixing...
[Pins open@8.4.2]
[Updates workflows to the current Node LTS]
[Adds .gitignore patterns]
[Drafts CHANGELOG entry]
✓ Auto-fixes complete!
Remaining manual items:
- Review 15 dependency updates
- 3 TODO comments need review
Create cleanup branch? (yes/no)The Championship Promise
"Pit crews service the car between every race. Your repos deserve the same attention."
Repo Maintainer - Championship Repository Hygiene "When brakes must work flawlessly, so must our repos."
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

