Skill doctor

Skill Doctor

Core principle

When a skill "doesn't work", the cause is almost never the content — it's the structure. Two failure modes explain ~90% of cases:

1. Never triggers → the frontmatter description is generic. It's the only text Claude always sees; it must list exact trigger signals AND exclusions.
2. Inconsistent outputs → the context is saturated. Everything loads on every use, the signal drowns. SKILL.md should stay under 500 lines; everything else belongs in references/ behind an explicit read condition.

Every sentence in a SKILL.md must change Claude's behavior. If it doesn't, it's noise — delete it.

When to use / not use

Use if: a skill misfires, under-triggers, over-triggers, drifts, or needs a pre-publication review. Do not use if: the user wants a brand-new skill built from scratch (that's creation, not repair — see Full toolkit note at the bottom).

Rule when information is missing

Make explicit assumptions, produce a first version, flag the assumptions. Ask at most 1–3 questions, and only if an assumption would be too risky. Never block.

Audit workflow

1. Read the whole skill

SKILL.md including frontmatter, plus every file in references/, templates/, scripts/. Never audit from the SKILL.md alone if other files exist.

2. Check promised vs. present

Every file pointed to by SKILL.md must exist. Phantom references silently degrade outputs — this is one of the most common defects in published skills.

3. Score against the 7-criteria grid

Read references/audit-grid.md and score each criterion 0–5: clarity, triggering, concision, reusability, testability, maintainability, robustness. Delivery threshold: 4/5 average.

4. Identify the dominant failure

Match symptoms to the anti-pattern table below. Name ONE dominant cause — a repair that fixes everything fixes nothing.

5. Produce the fix list, ranked by impact

Each fix: what to change, where, why it changes behavior.

6. Deliver the corrected version

Full corrected SKILL.md, not a diff. Preserve the author's intent and voice — repair the structure, not the project.

7. Test on 5 cases

Normal · vague · edge · missing info · out of scope (must NOT trigger). Binary verdict per case. Every failure becomes a rule, an example, or a constraint. Protocol details in references/audit-grid.md.

Anti-pattern table

Symptom	Structural cause	Fix
Never triggers	Generic description, no signals	Rewrite description: keywords, request types, exclusions
Triggers on wrong requests	No exclusions in description	Add explicit "do NOT use for..."
Inconsistent outputs	SKILL.md overloaded (500+ lines)	Move bulk to references/ with read conditions
References never read	Files not pointed from SKILL.md, or no condition	Add pointer + "read X only if Y"
Claude rewrites code instead of running scripts	No exact call documented	Document: python scripts/x.py <args>
Install broken	Frontmatter name ≠ folder name	Align both
Output varies wildly between runs	No imposed output format	Add a numbered output format section
Skill fabricates when input is bad	No missing-info rule	Add the assumptions-first rule (see above)

Imposed output format

Every audit follows this order:

1. Quick diagnosis — solid / to simplify / structurally broken, in 3 lines
2. Promised vs. present — list of phantom files, if any
3. 7-criteria scores — table with one-line cause per score below 4
4. Dominant failure — one named cause
5. Fix list — ranked by impact
6. Corrected SKILL.md — complete
7. 5-case test plan — with expected verdicts

Resources

• references/audit-grid.md — 7-criteria scoring grid + 5-case test protocol — read at steps 3 and 7
• templates/skill-md-template.md — clean SKILL.md skeleton — use when the corrected version needs restructuring from the ground up