agentleFS
Wolfe-JamWolfe-Jam/faf-skills/skills/repo-maintainer/SKILL.md

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

  • Other versions4 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 4

    1. duolahypercho/codex-router★ 4ksame name
    2. BaoBao1996121/crazy-harness★ 0same name
    3. freanocank/repo-maintainer★ 0same name
    4. 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.

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
  1. Distinctive:

    After major refactoring or before releases

    line 34
  2. Distinctive:

    Check git status for untracked patterns

    line 57
  3. Distinctive:

    Remove EOL runtimes (e.g. Node 16) from release workflows

    line 89
  4. Distinctive:

    After audit, generate prioritized task list:

    line 162
  5. Distinctive:

    Run checks in order of priority:

    line 288
  6. Distinctive:

    Create structured report with:

    line 296
  7. Distinctive:

    Never make changes without explicit approval.

    line 310
  8. Distinctive:

    When onboarding new devs

    line 404
  9. Distinctive:

    Document before cleaning (understand why artifacts exist)

    line 408
  10. Distinctive:

    Test after cleanup (ensure nothing broke)

    line 409
  11. Distinctive:

    Use TodoWrite for multi-step cleanups

    line 412
  12. Distinctive:

    Create issues for manual items

    line 413
  13. Distinctive:

    Document decisions in CLAUDE.md

    line 414

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- 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 git

Detection Strategy:

  • Check git status for 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 config

Red 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 configured

Common 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 belong

Pattern Recognition:

# Add to .gitignore based on artifacts found
*.faf.backup
.faf-dna.tmp
test-*.faf

6. 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/tokens

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

LOW (Nice to Have)

6. README Links

  • Issue: 2 broken links to old docs
  • Fix: Update URLs
  • Effort: 5 minutes

7. Unused Dependencies

  • Issue: depcheck found 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 -20

Step 2: Systematic Audit

Run checks in order of priority:

  1. Critical first - CI/CD failures, security issues
  2. Medium next - Dependencies, documentation gaps
  3. 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 version

MCP 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

ScoreTierSymbolStatus
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       → ✪ Trophy

Related Skills

  • /wjttc-builder · /wjttc-tester - generate + run championship-grade tests before a release
  • /faf-expert - master the .faf format + 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."

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.