How do I install the Doctor skill?

Run npx skillmds@latest add shivae372/doctor in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Doctor safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Doctor?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Doctor free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Doctor?

shivae372 (@shivae372) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Doctor by shivae372 — Agent Skill

Name: Doctor
Author: shivae372

Doctor

Self-heals this project's Claude Code setup. Diagnoses broken or missing pieces — skills with no SKILL.md, hooks referenced but absent or non-executable, invalid settings.json, bloated CLAUDE.md — scores health, and applies safe fixes. Use when something in the setup seems off, after edits to .claude/, when a hook or skill isn't firing, or on a `[heal]` nudge. Triggers: 'is my setup ok', 'fix my claude setup', 'why isn't my skill/hook working', '/doctor'.

shivae372 8a0ffd4 2.4 KB Updated Sep 17, 2026

File contents

Purpose

Keep the setup healthy without the user having to understand its internals. The diagnosis is fully deterministic (no guessing); repairs are explicit and safe.

When to use this

A hook/skill/command isn't behaving, or the user edited .claude/ by hand.
A [heal] nudge appeared (a tool failed repeatedly — see .claude/state/failures.jsonl).
Proactively after augment/forge writes new config.

Steps

1. Diagnose

python3 .claude/engine/doctor.py --json

Returns {score, errors, warnings, findings[]}. Each finding has where, problem, fix, and auto_fixable.

2. Apply the safe auto-fixes

python3 .claude/engine/doctor.py --apply

This performs only non-destructive repairs (e.g. chmod +x hooks). Everything else is left to you with a precise fix string.

3. Repair the rest, in order of severity

error first (a missing hook reference, a skill with no SKILL.md, invalid JSON). Fix the root cause: restore/author the file, correct the JSON, or remove the dead reference. For a skill dir missing SKILL.md, use forge (or delete it if obsolete).
warn next (non-executable hook already covered by --apply; oversized CLAUDE.md → trim and move detail into skills; agent missing frontmatter → add it).
info as time allows.

4. Re-check and learn

Re-run the diagnosis until errors: 0. If a failure pattern recurs, record it so the setup avoids it next time:

echo '{"category":"fix","text":"<what was broken> → <how fixed>","tags":["heal"]}' \
  | python3 .claude/engine/learn.py add

Output

A health score and a clean before/after: what was broken, what was auto-fixed, what you repaired, ending at 0 errors.

Guardrails

Auto-fix is safe-only; never delete user content to "fix" a finding without asking.
If a finding's root cause is ambiguous, show the user the finding and the proposed fix before applying it.

---name: doctordescription: Self-heals this project's Claude Code setup. Diagnoses broken or missing pieces — skills with no SKILL.md, hooks referenced but absent or non-executable, invalid settings.json, bloated CLAUDE.md — scores health, and applies safe fixes. Use when something in the setup seems off, after edits to .claude/, when a hook or skill isn't firing, or on a `[heal]` nudge. Triggers: 'is my setup ok', 'fix my claude setup', 'why isn't my skill/hook working', '/doctor'.---## PurposeKeep the setup healthy without the user having to understand its internals. Thediagnosis is fully deterministic (no guessing); repairs are explicit and safe.## When to use this- A hook/skill/command isn't behaving, or the user edited `.claude/` by hand.- A `[heal]` nudge appeared (a tool failed repeatedly — see `.claude/state/failures.jsonl`).- Proactively after `augment`/`forge` writes new config.## Steps### 1. Diagnose```bashpython3 .claude/engine/doctor.py --json```Returns `{score, errors, warnings, findings[]}`. Each finding has `where`, `problem`,`fix`, and `auto_fixable`.### 2. Apply the safe auto-fixes```bashpython3 .claude/engine/doctor.py --apply```This performs only non-destructive repairs (e.g. `chmod +x` hooks). Everything elseis left to you with a precise fix string.### 3. Repair the rest, in order of severity- **error** first (a missing hook reference, a skill with no SKILL.md, invalid JSON). Fix the root cause: restore/author the file, correct the JSON, or remove the dead reference. For a skill dir missing SKILL.md, use `forge` (or delete it if obsolete).- **warn** next (non-executable hook already covered by --apply; oversized CLAUDE.md → trim and move detail into skills; agent missing frontmatter → add it).- **info** as time allows.### 4. Re-check and learnRe-run the diagnosis until `errors: 0`. If a failure pattern recurs, record it so thesetup avoids it next time:```bashecho '{"category":"fix","text":"<what was broken> → <how fixed>","tags":["heal"]}' \ | python3 .claude/engine/learn.py add```## OutputA health score and a clean before/after: what was broken, what was auto-fixed, whatyou repaired, ending at 0 errors.## Guardrails- Auto-fix is safe-only; never delete user content to "fix" a finding without asking.- If a finding's root cause is ambiguous, show the user the finding and the proposed fix before applying it.

Frequently asked questions