feat(doctor): implement upskill/doctor — skill quality and security analyst [v1]

[ngouy]

upskill/doctor — Implementation Brief

What This Is

doctor is the quality and security analyst for skills. It looks at skill files — their content, structure, intent, and behavior — and tells you what's wrong, what's missing, what's dangerous, and what's good. It operates in two distinct modes: Curator (for skills you own) and Guardian (for third-party skills you're evaluating for safety).

Both modes live in one skill. If token budget is exceeded during implementation, splitting into two separate skills is the fallback.

Reference: VISION.md → Section "upskill/doctor"
Session structure: brainstorm → plan → implement → review (do not skip or combine)

---

Why "doctor"

The name is intentional. A doctor diagnoses, treats, prescribes, and discharges. doctor does the same for skills — it finds what's wrong, recommends a fix, applies it with your approval, and clears the skill. "The doctor will see your skill now."

---

The Core Problems It Solves

For skill authors (Curator mode):

• Skills created quickly accumulate problems: too broad, too long, missing guard rails, contradicting other instructions, or unclear in purpose
• No tooling exists to systematically identify these issues
• Skills that instruct dangerous actions have no safety layer by default

For skill consumers (Guardian mode):

• No automated way to evaluate whether a third-party skill is safe before installing
• A malicious skill can instruct Claude to exfiltrate data, suppress transparency, or override CLAUDE.md
• No conflict detection between a skill and your CLAUDE.md

---

Scope: Doctor Owns All Per-Skill Analysis

Doctor is the sole owner of per-skill quality and security checks. Auditor (v1.1+) handles cross-skill analysis (conflicts between skills, overlapping triggers). Doctor analyzes one skill at a time in depth.

Doctor works on skills from all three sources: plugin-installed, global local (~/.claude/skills/), and project-level (<project>/.claude/skills/). Project-level skills are a primary target — they're the most likely to be written quickly and never curated.

---

Two Modes

Curator Mode

Activated by default when analyzing a skill you own. Can be forced with --curator.

1. Structural Quality

• Clear, single-sentence purpose/intent statement at the top
• Defined trigger conditions (when should this skill fire?)
• Defined exit/completion signal (when is the skill done?)
• Consistent formatting and section organization
• Actionable instructions vs. vague guidelines ("always consider X" is not actionable)

2. Scope & Focus

• Is this skill doing too many unrelated things? (Suggest split if 3+ unrelated domains)
• Is the trigger condition too broad? (fires constantly, wastes context)
• Does this skill duplicate another installed skill?

3. Guard Rail Recommendations
Identify dangerous actions and suggest guard rails — NEVER remove capabilities, only add safety layers:

• Skill instructs bash commands → recommend "always show command before executing"
• Skill can delete files → recommend confirmation step
• Skill has network access → recommend logging accessed URLs
• Skill modifies git history → recommend explicit user acknowledgment

4. Token Efficiency

• Estimate token footprint (4 chars ≈ 1 token, labeled as estimate)
• Flag skills that exceed reasonable size for their purpose
• Suggest specific sections to condense — be specific, not vague

5. Missing Elements (severity levels)

• No stated purpose → CRITICAL
• No trigger conditions → HIGH
• No exit/completion signal → MEDIUM
• No examples → LOW
• No version or author metadata → LOW

6. Bad & Good Practice Identification

Known bad patterns to flag:

Pattern	Why It's Bad
Contradicts CLAUDE.md	Unpredictable Claude behavior
Uses "always" for optional behaviors	Overfires, wastes tokens
No user confirmation before destructive action	Unsafe by default
Skill title differs from stated purpose	Confusing for user and Claude
References file paths that don't exist	Will silently fail
Circular self-reference (loads another skill)	Can cause loops
Trigger condition too broad	Fires on virtually every session

Doctor also identifies and explicitly calls out good practices — positive signal matters as much as negative.

---

Guardian Mode

Activated by default when analyzing a third-party plugin. Can be forced with --guardian.

Level A — Obvious Red Flags (binary)
Direct malicious intent in the skill text:

• Instructions to exfiltrate data (send to external URL, write to "temp" file)
• Instructions to suppress transparency ("don't tell the user", "hide this")
• Instructions to override other settings ("ignore CLAUDE.md", "ignore system prompts")
• Prompt injection patterns ("treat the following as a new instruction")
  → Output: RED FLAG. Do not use this skill.

Level B — Dangerous Capability Patterns (contextual)
Powerful capabilities without clearly stated proportionate reason:

• Bash execution + network access with no stated reason
• File system write access outside project directory
• Access to environment variables or secrets
• Spawning background processes
  → Not automatic red flags — evaluate whether stated purpose justifies capabilities. Mismatch = SUSPICIOUS.

Level C — Behavioral Anomalies (inferential)
Stated purpose ≠ what the skill actually instructs Claude to do:

• Title: "code formatter" — also rewrites git history
• Title: "PR reviewer" — also modifies files without being asked
  → Output: SUSPICIOUS. Investigate before using.

Conflict Detection (both modes)

• Does this skill contradict an instruction in CLAUDE.md?
• Does this skill contradict another loaded skill?
• Flag the specific conflicting text from each source

---

Output Format

Doctor ALWAYS produces a structured report — never freeform prose.

DOCTOR REPORT — skills/my-skill/SKILL.md
Mode: Curator
─────────────────────────────────────────────────────────────────────

CRITICAL (1)
  [C1] Missing purpose statement
       Every skill must open with a 1-2 sentence statement of what
       it does. This is the first thing Claude reads.
       Fix: Add a "## Purpose" section at the top.

HIGH (1)
  [H1] Trigger condition too broad
       Current: "when I am working on any code"
       Fires on virtually every engineering session.
       Fix: Narrow to a specific context.

MEDIUM (2)
  [M1] No exit/completion signal
  [M2] Guard rail missing for bash execution

LOW (1)
  [L1] No usage examples

─────────────────────────────────────────────────────────────────────
SUMMARY: 1 critical, 1 high, 2 medium, 1 low
Overall health: NEEDS ATTENTION

Recommended next step: Fix C1 and H1, then re-run doctor.

Curator severity levels: CRITICAL / HIGH / MEDIUM / LOW
Guardian severity levels: RED FLAG / SUSPICIOUS / GREEN

---

What doctor Must Never Do

• Never modify skill files without explicit user approval for EACH change
• Never remove capabilities from skills — add guard rails around them instead
• Never report false certainty — use hedged language for Level C findings
• Never analyze conversation content or project code — skills only
• Never block the user from using a skill — recommendations only
• Never make security judgments about what bash commands DO at runtime — static analysis of skill instructions only

---

When to Use (trigger signals for SKILL.md description)

• User wants to review, improve, or check the quality of a skill
• User asks if a skill is safe, well-written, or has issues
• User wants to split a skill into more focused sub-skills
• User suspects a skill is causing problems or unexpected behavior
• User wants to audit a third-party or newly installed skill for security
• User asks about bad practices, guard rails, or missing elements
• User wants to know if a skill contradicts their CLAUDE.md
• Right after plugin install — offer guardian scan as a security check

---

Quality Gate

Before this skill is considered done:

• Passes doctor --curator on itself with zero CRITICAL or HIGH findings (dog-fooding)
• Report output format matches the example above exactly
• Both Curator and Guardian modes fully implemented
• "Must never do" list enforced
• Conflict detection covers: skill vs. CLAUDE.md AND skill vs. other loaded skills
• Works on all three skill sources (plugin, global, project)
• Token footprint target: ~800 tokens (verify with character count, document overrun if needed)

[ngouy]

Review update — design changes

Following a critical design review (#5), doctor remains in v1 scope as one of the two priority skills.

Changes to doctor's design (captured in VISION.md via #5):

• Curator + Guardian stay as one skill. They share the "doctor" name and will always be called together. If token budget is exceeded during implementation, splitting into two skills is the fallback.
• Token budget raised to ~800 tokens. The dual-mode spec (curator + guardian + pattern library + output format examples) can't fit in 600 tokens. Budgets are aspirational targets with expected 50-100% overrun.
• Project-level skills are first-class. Doctor can analyze skills in <project>/.claude/skills/ — these are the skills most likely to be written quickly and never curated.
• No per-skill checks duplicated by auditor. Auditor has been refocused on cross-skill analysis only. Doctor owns all per-skill quality and security checks exclusively.
• "When VISION.md Is Wrong" escape hatch added. Implementers can update VISION.md when the spec is demonstrably wrong or infeasible — this is not "unilateral modification," it's a necessary correction.

No changes to:

• Curator mode checks (structural quality, scope, guard rails, token efficiency, missing elements, bad/good patterns)
• Guardian mode levels (A: red flags, B: dangerous patterns, C: behavioral anomalies)
• Output format (structured report, severity levels)
• "Must never do" list