| name | code-health |
| description | Structural code-health metrics, the rolled-up CodeHealth score, and the Code Health Dashboard pipeline (Maintainability Index, cyclomatic/cognitive complexity, churn×complexity hotspots, coupling/instability, change-coupling, duplication, circular imports). Measures + trends + renders; the quality-butler composes it. Use to instrument a repo, take a reading, or refresh the dashboard. |
Code Health Skill
Owns the structural-health concern: how maintainable, well-structured, and
low-risk the code is — measured, trended, and rolled up into one CodeHealth
grade and a published dashboard. Bundles repo-agnostic scripts that run against
whatever repo invokes them (config from the repo root).
Separation of concerns (where this sits)
One dashboard, several producers — each skill owns its dimension:
| Concern | Owner | Feeds the roll-up |
|---|
| Structural metrics (MI, complexity, hotspots, coupling, change-coupling, duplication, cycles) + CodeHealth roll-up + dashboard render/stamp/trend | code-health (this) | Maintainability, Structure, Resilience, Type & size |
| Docs / TSDoc / wiki publish | code-readability | Documentation |
| Coverage / lint / sprint planning | code-quality | (Test trend, informational) |
| SAST · secrets · SCA (per-PR + dep advisories) | security-audit | Security |
This skill measures and aggregates; it does not annotate docs, write tests, or
run the full security toolchain — it reads those signals (doc%, npm-audit counts,
coverage) where they live and rolls them into the score. The quality-butler
agent is the orchestrator that runs all four and publishes the dashboard.
Configure for your project
Add code-health.config.json at the repo root (defaults assume a single src/):
{
"dirs": ["apps/web/src"],
"docDirs": ["apps/web/src/components", "apps/web/src/hooks", "apps/web/src/services",
"apps/web/src/utils", "apps/web/src/types", "apps/web/src/config"],
"coverageWorkspaces": ["apps/web"],
"tsconfig": "apps/web/tsconfig.json",
"historyDir": "code-health",
"window": "365 days ago"
}
blobBase (GitHub file links) is auto-derived from origin; override if needed.
changeCoupling thresholds and thresholds.{miGreen,miYellow,dupMinLines} are
tunable. All output goes to <historyDir>/*-history.tsv (the trend) +
codehealth-stamp.json (the dashboard facts).
Install (repo devDeps): typescript, dependency-cruiser, madge. eslint
(complexity), jscpd, and vitest --coverage are invoked via the repo's existing
toolchain / npx.
Modes
instrument — first-time setup in a repo: write code-health.config.json,
add devDeps + npm run aliases (see below), run run-all.mjs once to seed the
history TSVs, and create/stamp the Code-Health-Dashboard wiki page.read — take a fresh reading: node <skill>/scripts/run-all.mjs (all
producers then the roll-up). Add --no-write to print without appending history.refresh — regenerate the dashboard: run-all.mjs --stamp <wiki>/Code-Health-Dashboard.md <wiki>/Home.md fills the <!--ch:*--> markers.
Suggested package.json aliases. Point them at wherever the skill is installed —
.claude/skills/code-health/scripts/… when it's vendored into the project (the quality-butler
model, shown below), or ~/.claude/skills/code-health/scripts/… for a global install:
"mi:report": "node .claude/skills/code-health/scripts/maintainability-report.mjs",
"complexity:report": "node .claude/skills/code-health/scripts/complexity-report.mjs",
"hotspot:report": "node .claude/skills/code-health/scripts/hotspot-report.mjs",
"coupling:report": "node .claude/skills/code-health/scripts/coupling-report.mjs",
"change-coupling:report":"node .claude/skills/code-health/scripts/change-coupling-report.mjs",
"duplication:report": "node .claude/skills/code-health/scripts/duplication-report.mjs",
"codehealth:report": "node .claude/skills/code-health/scripts/run-all.mjs"
The CodeHealth roll-up
A 0–100 score (letter grade A–F) over six dimensions, each normalized against
documented anchors then weighted. Run the producers first — the roll-up reads
their latest TSV rows; run-all.mjs sequences this for you.
| Dimension | Weight | Source |
|---|
| Documentation | 20% | doc coverage % |
| Maintainability | 25% | MI health proportion (green + ½·yellow) / files |
| Structure | 20% | circular imports + cross-layer change-coupling |
| Resilience (worst file) | 10% | lowest single-file MI |
| Type & size safety | 15% | any count + files > 500 LOC |
| Security (deps) | 10% | npm-audit advisory counts |
Full formulas, bands, and the "why health-proportion not the MI mean" rationale
live in references/methodology.md. Grade bands: A ≥ 90 · B 80–89 · C 70–79 ·
D 60–69 · F < 60.
The dashboard
Code-Health-Dashboard.md (wiki) is the single rendering. Hand-authored prose +
<!--ch:NAME-->…<!--/ch:NAME--> markers that stamp-codehealth.mjs fills from
codehealth-stamp.json, so the prose never drifts from the numbers. The marker
stamping + wiki clone/commit/push are the shared /wiki-publish substrate
(stamp-codehealth.mjs delegates to it, prefix ch, with an inline fallback so
code-health stays self-contained). Structure:
generated executive summary (ch:exec) → headline grade → generated metrics by
business outcome (risk / throughput / key-person, ch:outcomes) → detailed views (MI pie,
hotspots, coupling) → generated Improve & ROI (ch:roi) → glossary. Mirror the layout in
references/methodology.md.
The interpretation layer (ch:exec / ch:outcomes / ch:roi) is produced by
codehealth-report.mjs, not hand-authored — so every install ships plain-language verdicts
(✅/⚠️/❌), direction-of-travel (▲/▼ vs last reading), a "so what," and a citable benchmark next to
each number, legible to the non-technical leaders these dashboards get presented to. The audience
personas and encoding principles behind it live in references/methodology.md and the
Audience-Personas wiki page.
Stamp facts include a ch:trend score-over-time chart (a Mermaid
xychart-beta line of the last ~12 codehealth-history.tsv readings, with a
Unicode-sparkline fallback and an "insufficient history" note when there are <2
readings) plus ch:doc_pct / ch:security for the CodeHealth roll-up's
documentation and dependency-security dimensions. The full marker set lives in
references/methodology.md.
Quality-coverage checklist (butler feature)
quality-checklist.mjs is a butler-level tracker that ships here (it reuses this
skill's config + the /wiki-publish stamper). It probes the repo — CI workflows,
ESLint config, package.json, pre-commit, the code-health history, installed
skills, and (with --wiki) published pages — for every capability the quality
skills offer, and classifies each ✅ enabled / ⚠️ partial / ❌ gap / ➖ n/a. It exists
to stop audits from forgetting things: a capability that's available but never
turned on is a silent gap (e.g. a metric measured but never made a CI gate).
node <skill>/scripts/quality-checklist.mjs --wiki <wiki> --stamp <wiki>/Quality-Coverage.md
Writes <historyDir>/quality-checklist.json and stamps the <!--ql:*--> markers on
the Quality-Coverage dashboard. The butler runs it in its weekly document step.
Trend it (optional)
Schedule the butler (or a maintainability.yml workflow) weekly to accumulate the
*-history.tsv rows and re-stamp the dashboard, turning a one-time reading into
an early-warning trend.
Where the trend lives: the <historyDir>/*-history.tsv + stamp JSON are
generated artifacts — gitignore them on the default branch. The durable trend
belongs on the butler's butler-state branch (the quality-butler workflow
restores it before a run and persists it after), so it survives ephemeral CI
runners without the agent ever pushing to the default branch. Committing the trend
to the default branch instead leaves a snapshot that silently goes stale.
Don'ts
- Don't annotate docs or write tests here — that's code-readability / code-quality.
- Don't hardcode repo paths in the scripts — everything comes from config.
- Don't stamp a dashboard without running the roll-up first (stale
codehealth-stamp.json).
Files
scripts/config.mjs — shared config loader + helpersscripts/{maintainability,complexity,hotspot,coupling,change-coupling,duplication,security,coverage}-report.mjs — producersscripts/{check-circular-deps,check-doc-coverage}.mjs — gate-able checksscripts/codehealth-report.mjs — the roll-up + stamp facts (incl. the trend sparkline)scripts/stamp-codehealth.mjs — fill dashboard markersscripts/run-all.mjs — produce everything in order (+ optional --stamp)scripts/agnostic-report.mjs — language-agnostic size/complexity backend (via scc) for non-TS reposscripts/portfolio-report.mjs — multi-repo CodeHealth rollup → portfolio dashboardscripts/quality-checklist.mjs — capability-coverage checklist → Quality-Coverage dashboardreferences/methodology.md — formulas, anchors, glossary, dashboard template
