🩺 Skill Doctor

A meta-skill for Claude Code that gives your other skills a health checkup — and tells you exactly what to trim, delegate, or de-scaffold.

[!NOTE]
Inspired by Matt Pocock. Skill Doctor is built entirely on the method Matt Pocock shared in his talk Building Great Agent Skills: The Missing Manual (AI Engineer). All credit for the underlying approach — who-triggers → structure → deletion test, leading words, and the deletion test itself — goes to him. Skill Doctor just packages that method into a runnable skill.
📺 Watch the original talk: https://www.youtube.com/watch?v=UNzCG3lw6O0

Skill Doctor reviews any Claude Code Skill using the method from Matt Pocock's talk Building Great Agent Skills: The Missing Manual. It diagnoses only — it never edits your files unless you explicitly ask it to.

v2.0 extends Pocock's prompt-trimming method into an agent-workflow architecture review: it also checks whether the skill still matches how it actually runs, who (model / script / runtime) should own each step, which rules are leftover scaffolding for older models, and whether side effects can be retried safely. See What's new in 2.0.

If your SKILL.md keeps getting longer, you keep adding rules, and yet the agent listens less — you've probably fallen into what Pocock calls "Skill Hell." Skill Doctor turns a bloated skill back into an executable entry point.

Why?

Developers keep adding rules when a skill misbehaves. A few rounds later, SKILL.md becomes a junk drawer nobody dares to delete from. The fix isn't more rules — it's a review:

Who triggers it → Structure → Deletion test

Skill Doctor runs exactly that review and hands you a prioritized report.

Install

Copy the skill-doctor/ folder into your Claude Code skills directory:

git clone https://github.com/isalicema/skill-doctor.git
cp -r skill-doctor ~/.claude/skills/

Then just tell Claude Code:

"which skills need a checkup?" → runs the onboarding scan
"review my-skill" → full checkup report
"refactor my-skill" → applies fixes (only after you approve)

The five gates it checks

Gate	Question	What it catches
0. Runtime reality (2.0)	Does the doc match how the skill actually runs?	Stale model names / paths, thresholds that disagree between prompt and validation script ("two sources of truth"), foreign rules from other systems
1. Who triggers it	Auto or manual? Is the trigger phrase consistent?	High-impact skills set to auto-trigger; trigger words scattered across files; context-cost bloat
2. Structure	Steps vs. reference material vs. scripts?	Templates / glossaries / long lists welded into the main file; mechanical steps the model is taught to hand-type. Goal: main file readable in 10 minutes
3. Deletion · Delegation · Scaffold (extended in 2.0)	Delete it — does behavior change? Should the model, a script, or the runtime own it? Rule or training wheel?	No-ops, duplication, sediment; judgment mixed with deterministic work; scaffolding built for older models that now just boxes the new one in. Protects the leading words that actually steer behavior
4. Transaction & recovery (2.0)	If it fails halfway, can you re-run safely?	Writing state before delivery is confirmed ("zombie success"), duplicate sends on retry, no receipt / commit marker

Skills that only write or research run gates 1–3; skills with schedules, outbound messages, or state writes must run all five.

What's new in 2.0

	v1.0	v2.0
Role	Prompt editor	Agent-workflow architecture reviewer
Gates	Trigger → Structure → Deletion	Runtime reality → Trigger → Structure → 3-way test → Transaction & recovery
Deletion test	One question: does behavior change?	Three: Deletion (does it matter?), Delegation (model vs. script vs. runtime), Scaffold (permanent outcome guardrail vs. training wheel for an older model)
Triage scan	Length + split + recency	Adds a side-effect risk score (outbound messages, state writes, schedules, external archives) — short skills with dangerous side effects no longer hide
After the refactor	Line count + keyword check	Acceptance matrix: leading words survive, `bash -n` + dry-run on new scripts, and a note on what responsibility moved from model to script/runtime

The two consent gates are unchanged: report first, edit only after you say so.

🔒 Two consent gates (safety first)

Skill Doctor is deliberately manual-trigger and never touches your files without permission:

Gate 1 · Checkup — once you pick a skill, it only reads and reports. No edits.
Gate 2 · Refactor — it will not change a single file until you explicitly say "refactor / optimize / go ahead."

A report is not authorization to edit. Even when a problem is obvious, it stops at the recommendation and waits for you.

Before any refactor it backs up the target (cp SKILL.md SKILL.md.bak-<date>) and runs an acceptance check afterwards (keyword survival, bash -n and dry-run for any new script), so nothing gets lost in the move.

Onboarding: don't know where to start?

Run the triage scan to rank your installed skills by checkup priority:

bash ~/.claude/skills/skill-doctor/scripts/scan-skills.sh

SKILL                            lines split   risk  edited(d)   advice
----------------------------------------------------------------------------------------
some-big-skill                     662   yes     80       16   🔴 high priority
daily-report-bot                   120    no    110        3   🔴 high priority (sends + state)
another-skill                      180   yes     40       53   🟠 recommended
tidy-little-skill                   56    no      0      109   🟢 healthy

It ranks by main-file length, whether reference/script files have been split out, a side-effect risk score, and recent edits. The risk score is a keyword heuristic (outbound messaging, state writes, schedules/hooks, external archives) — treat it as a pointer, not a verdict. (The filesystem can't see real usage frequency, so it asks you to confirm which ones you actually use most before recommending a checkup.)

Worked example: slimming a `collection-manager` skill

A real before/after. collection-manager is a skill that saves and summarizes articles in four steps.

Before — 111 lines. The four-step workflow was sound, but a ~40-line Markdown output template was pasted right into the middle of Step 3, and the naming rules were a separate trailing section. The steps were drowning in reference material.

Checkup found:

① Entry — the real trigger phrase lived only in a separate memory file, not in the skill's description. Entry truth was split across two places.
② Structure 🔴 — the output template (~40% of the file) is reference material, not a step. It's only consulted while writing, so it belongs in a side file.
③ Deletion test — a couple of lines in Step 3 repeated the same "distill, don't summarize" idea. But the core leading lines ("read the whole thing before writing") genuinely changed behavior — keep those.

After — 57 lines (−49%). The template + naming rules moved to references/template.md; Step 3 kept three crisp quality standards plus one pointer. The trigger phrase was added back into description. No leading words were lost.

collection-manager/
├── SKILL.md                 57 lines  ← steps + one pointer
└── references/
    └── template.md          ← the output format, consulted on demand

The main file is now a 10-minute read and an executable entry point again, instead of a long document.

Credits

Method (v1.0 core): Matt Pocock, Building Great Agent Skills: The Missing Manual (AI Engineer).

Built by Machiwhale Studio 🐋 as a meta-skill — and yes, Skill Doctor passes its own checkup (main file under 80 lines, reference material and the triage script split out).

v2.0 extends Pocock's method with ideas from reviewing agent workflows that run on schedules and send messages; the extensions are this project's own and any mistakes in them are not his.

License

MIT