repo-health
Skill8 starsChanged 5 days agoMITView on GitHub
Periodic AI-readiness report — 9-asset action checklist, audit drift, and suggest-only reviewer-feedback phrases mined from the last N merged PRs.
6 other projects use a version of this.
Adopted by
Most recently taken up by
- dataGriff/skillstheir own version, first seen Nov 1, 2026
- damsleth/SKILLStheir own version, first seen Oct 25, 2026
- Al-Baqshi/consistent.ceotheir own version, first seen Oct 17, 2026
- Sassy-Dog/skillstheir own version, first seen Oct 8, 2026
- exerias21/brainstorm-toolkittheir own version, first seen Oct 4, 2026
- calebnewtonusc/Chewbaccatheir own version, first seen Aug 11, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- calebnewtonusc/Chewbacca★ 8same name
- Al-Baqshi/consistent.ceo★ 1same name
- damsleth/SKILLS★ 1same name
- Sassy-Dog/skills★ 1same name
- dataGriff/skills★ 0same name
- exerias21/brainstorm-toolkit★ 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 repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- batch-fixSkill
- brainstormingSkill
- code-review-and-qualitySkill
- code-simplificationSkill
- context-engineeringSkill
- fixSkill
- handoffSkill
- implementSkill
- incremental-implementationSkill
- instructionsSkill
- lessonsSkill
- mtk-doctorSkill
- mtk-setupSkill
- mtkSkill
- planning-and-task-breakdownSkill
- pre-commit-reviewSkill
- prior-work-checkSkill
- promote-lessonSkill
- research-contextSkill
- security-and-hardeningSkill
- setup-auditSkill
- setup-bootstrapSkill
- setup-refreshSkill
- spec-drift-detectionSkill
- spec-driven-developmentSkill
- subagent-implementationSkill
- tech-stack-dotnetSkill
- tech-stack-pythonSkill
- tech-stack-typescriptSkill
- verification-before-completionSkill
- workflow-artifactsSkill
- writing-skillsSkill
The file
Files
Repo health
Overview
One report from three scripts — repo-health-score.sh (nine assets, pass/partial/fail/na plus action_needed; no medal or aggregate; assets 5–6 read na outside the MTK checkout; rubric in .claude/references/repo-health-assets.md), audit-drift-check.sh, and pr-review-mine.sh (imperative reviewer phrases recurring across ≥2 merged PRs, tagged [MINED:feedback], suggest-only; heuristics and denylist in .claude/references/pr-mining-patterns.md).
Writes .claude/repo-health-latest.md (always) and .claude/repo-health-latest.json (with --json); both are gitignored.
When To Use
- "Is this repo AI-ready?", "repo health", "what should we improve?", "mine our PRs", "what do reviewers keep asking for?"
- Periodically, before a major release, or after
/mtk-setup --audit.
When NOT To Use
- MTK usage numbers →
mtk-doctor --usage. - Inside the build loop, or on a repo with fewer than 3 merged PRs (mining has no signal; run with
--no-mining).
Workflow
- Flags.
--prs N(1..50, default 10),--json,--no-mining. - Checklist.
bash scripts/repo-health-score.sh(add--jsonfor the JSON file). The nine assets are canonical; never add, drop or re-grade one at runtime — a change goes through the reference and the script. Audit drift (best-effort, never blocks):
CONST_DOC=AGENTS.md; [ -f "$CONST_DOC" ] || CONST_DOC=CLAUDE.md for doc in "$CONST_DOC" .claude/references/architecture-principles.md .claude/references/conventions.md; do [ -f "$doc" ] || continue bash scripts/audit-drift-check.sh "$doc" || true # exit 1 = drift doneDrift annotates asset 2 as
🟨 audit drift: N citations; it never changes the status. Unstamped docs are skipped silently.- Mining (unless
--no-mining):bash scripts/pr-review-mine.sh --prs <N>. Fail-soft: without an authenticatedghit printsSkipped: <reason>and exits 0 — report that line, never phrases from memory. A phrase needs ≥2 distinct PRs; one reviewer repeating it in one PR is not a team norm. Boilerplate that slips through ("great work") goes on the## Denylistofpr-mining-patterns.md, then re-run; the denylist is never bypassed for one run. - Top 3 actions. Candidates: every
action_neededasset and every mined phrase cited by ≥3 PRs. Rank AI Context > Onboarding > Toolkit > mined phrase. One sentence each, naming the file or command. - Write the report to
.claude/repo-health-latest.md: checklist, drift table, mining section,## Top 3 actionable changes. With--json, also.claude/repo-health-latest.jsonas{ "scorecard": {...}, "mining": {...}, "top3": [...] }. Write the file even when the engineer asks for chat only; echo the path, theNeeds actionline and the top 3. - Publish per
.claude/references/artifact-publishing.mdafter the file is on disk (silent no-op when the tool is unavailable orMTK_ARTIFACT_PUBLISH=0).
Never edit architecture-principles.md from this skill. A mined phrase becomes a principle only when the engineer promotes it, one phrase at a time, with the [MINED:feedback] tag and its PR numbers, after seeing the diff.
Verification
.claude/repo-health-latest.mdexists with aNeeds action:line, the nine-asset table and a "Top 3 actionable changes" section.bash scripts/repo-health-score.sh --json | jq '.action_needed'is an array; the output carries no medal or score.- The mining section cites PR numbers (
#<n>) for every phrase, or readsSkipped: <reason>. architecture-principles.mdis unchanged.
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.

