skill-doctor

Mechanical audit of your skill resolver system. Three checks, one Python script, no LLM in the loop.

What it does

1. Reachability — every {brain_root}/skills/<name>/SKILL.md has at least one row in {brain_root}/AGENTS.md mapping a phrase to <name>. "Surgeon on staff but not in the hospital directory" — if a skill exists but nothing routes to it, it's invisible.
2. Orphan phrases — every AGENTS.md row points at a skill that actually exists (not archived, not typo'd). Catches stale rows after a skill retires.
3. DRY overlap — no two active skills claim the same trigger substring in their SKILL.md description: frontmatter. When overlap is legitimate, the fix is a discriminator row in AGENTS.md under "Known DRY pairs." When overlap is a bug, the fix is narrowing the SKILL.md description.

How to run

python3 {brain_root}/skills/cerebro-doctor/scripts/check_resolvable.py

Optional flags:

• --root <path> — override Brain root detection (default: walk up from script location)
• --format json — machine-readable output for daily cron integration
• --quiet — only print if there's drift

Exit codes:

• 0 — clean
• 1 — reachability drift (unreachable skill or orphan phrase)
• 2 — DRY overlap found
• 3 — both

Scope contract

• Reads: {brain_root}/skills/*/SKILL.md, {brain_root}/AGENTS.md, {brain_root}/skills/_archive/ (to disambiguate retired from missing)
• Writes: nothing. Read-only audit.
• MCP / tools: Python stdlib only. No network, no external models.
• Network egress: none.
• Surface: Claude Code (pure FS read). No git operations.
• Credentials: none required.
• Escalation triggers: if the script can't parse a SKILL.md frontmatter cleanly, it reports PARSE_ERROR for that file and keeps going. Does not abort.

Filing rules

• Writes no Brain output. The script prints to stdout; callers decide whether to file the report.
• If a daily cron wraps this, it can file a digest at {brain_root}/audits/<date>-skill-doctor.md — that's the cron's filing rule, not this skill's.

Known limitations (V0)

• DRY check uses naive substring matching on description text. False positives are possible (e.g., "find clients" vs "find solicitations" both contain "find" — the check uses multi-word phrases, not single words, to dampen this).
• Script-callability check (verifying every referenced script is callable) is deferred to V1 — V0 only does reachability + DRY.
• No --fix mode. Drift surfaces; operator or next session authors the fix.

Rollback

Delete {brain_root}/skills/cerebro-doctor/. AGENTS.md keeps working as a human-readable registry; only the machine check goes away.

Related

• {brain_root}/AGENTS.md — the resolver registry this audits
• {brain_root}/skills/brain-setup/ — scaffolds the Brain this audits
• {brain_root}/skills/sessionstart/ + {brain_root}/skills/sessionend/ — session rituals that consume a healthy resolver

References (auto-wikilinks)

• [[-skill-doctor]]
• [[SKILL]]