Skill doctor

Skill dhruba-datta/claude-papercuts/skills/skill-doctor

Ten Claude Code skills that fix bugs Anthropic closed as 'not planned'.

Install

npx -y skills add dhruba-datta/claude-papercuts --skill skill-doctor

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Diagnose why a SKILL.md isn't auto-invoking. Use this skill when the user runs /claude-papercuts:skill-doctor, asks why their skill won't trigger, mentions a skill that Claude keeps ignoring, or wants a lint pass on a SKILL.md they're writing. Runs lint.py to flag missing trigger phrases, vague descriptions, descriptions that overlap with built-in tool training (the root cause of issue #30387), names that aren't kebab-case, and length issues outside Anthropic's 50–1024 char bound.

SKILL.md

4.2 KB, 961 tokens by cl100k_base, as published. Nobody here has run it

skill-doctor — why isn't my skill auto-invoking?

Fixes: root cause of #30387 — "Custom skills not reliably auto-triggered. The model's training-time knowledge competes with and takes precedence over skill instructions."

What this prevents

"Skills for git/shell operations are ignored ~50% of the time." — issue #30387

When a SKILL.md description says "use for git operations", the model's training-time knowledge of git wins. The skill is never invoked. skill-doctor lints SKILL.md files against the same heuristics Anthropic's own template authors apply implicitly:

Check	Severity	Why it matters
`name:` present and kebab-case	error	Plugin loader rejects otherwise
`description:` length 50–1024	error	Anthropic's published bound
Description has trigger phrase	warn	Without "Use this when …", the model has nothing to route on
Description avoids vague words	info	"helper", "utility", "manager", "toolkit" — too generic
Description avoids training overlap	warn	"edits files", "git operations", "runs shell" — built-in tool wins
Description under 80 chars	warn	Not enough context to route to the right skill

How to invoke (the actual procedure)

If the user names a specific SKILL.md path, run:

${CLAUDE_PLUGIN_ROOT}/skills/skill-doctor/lint.py <path>

If the user wants a sweep of every installed skill, run:

${CLAUDE_PLUGIN_ROOT}/skills/skill-doctor/lint.py --all

Show the script's output verbatim. The severity glyphs (✗ error, ⚠ warn, · info) and the issue codes (e.g. training-overlap, no-trigger) are the value. Don't summarize the categories — the per-skill report is what the user came for.
If the user asks for help fixing a specific issue:
- For training-overlap: rewrite the description to name the specific workflow the skill owns ("apply database migrations" not "for database operations").
- For no-trigger: add a sentence starting with "Use this when …".
- For desc-thin: expand to include one concrete invocation example and one trigger phrase.
Never auto-modify a SKILL.md. Suggestions are for the user to apply themselves.

What gets discovered by `--all`

The same locations as skill-budget:

~/.claude/skills/<name>/SKILL.md
<cwd>/.claude/skills/<name>/SKILL.md
~/.claude/plugins/*/skills/<name>/SKILL.md

When to auto-invoke

User runs /claude-papercuts:skill-doctor
User asks "why isn't my skill triggering?"
User mentions a skill that Claude keeps ignoring
User says they just wrote a new SKILL.md and wants it reviewed

What this skill does NOT do

It does not modify SKILL.md files. Suggestions only.
It does not lint the body of the SKILL.md (the markdown after the frontmatter) — only the frontmatter and description.
It does not validate allowed-tools: glob syntax. Claude Code's plugin loader does that.
It does not (yet) run the skill to verify it triggers. A "trigger-fuzz" mode is planned for a future release.

Configuration

# JSON output for piping into other tools / CI
${CLAUDE_PLUGIN_ROOT}/skills/skill-doctor/lint.py --all --json

# Lint a specific path
${CLAUDE_PLUGIN_ROOT}/skills/skill-doctor/lint.py path/to/SKILL.md

# Scan a different project
${CLAUDE_PLUGIN_ROOT}/skills/skill-doctor/lint.py --all --cwd /path/to/proj

Deprecation plan

If Anthropic ships a built-in SKILL.md linter (e.g. via claude plugin validate), this skill becomes a duplicate and gets deprecated in the next monthly release with the date.