skillspec doctor is a static risk assessment command for agent skills. Given any SKILL.md — or a directory of skills — it answers a single question without invoking a model:
If an agent reads this skill as prose, how likely is it to miss, distort, skip, over-trigger, under-trigger, or fail to prove the instructions that matter?Doctor measures observable source-shape signals — activation body size, position of load-bearing obligations, instruction density, implicit dependencies, missing test surfaces — and converts them into a scored risk report. The report is a baseline of the skill at inspection time. It is not a grade of domain knowledge or a claim that a specific run failed.
Risk categories
Discovery risk — frontmatter and activation metadata
Discovery risk — frontmatter and activation metadata
Before any body text is loaded, the harness uses
SKILL.md frontmatter to decide whether to activate the skill. Doctor checks whether that discovery surface is strong enough to route reliably.Findings in this category:Research basis: Claude Code uses
SKILL.md frontmatter — especially description and when_to_use — to decide when to load a skill automatically. Listing budgets can shorten or drop descriptions entirely.Context load risk — token count vs. balanced target
Context load risk — token count vs. balanced target
Doctor estimates how many tokens the
SKILL.md body contributes at activation. More active prose means more competition for attention and less space for task state, evidence, and tool output.Findings in this category:Research basis: Advertised context length is not the same as reliable usable context across tasks (RULER, Hsieh et al. 2024). Context compaction can drop governance constraints in long-horizon agent runs (Chen 2026).
Primacy-bias risk — important rules buried late
Primacy-bias risk — important rules buried late
Load-bearing instructions buried after 60% of the activation body are statistically less reliably used than instructions near the beginning or end. Doctor flags modal obligations (
must, never, ask, check) that appear late.Finding: primacy_bias_late_obligations — score penalty: 10 pts.Each flagged obligation carries position metadata:body_line_percentandbody_token_percentposition_band:early(0–20%),early_middle(20–40%),middle(40–60%),late_middle(60–80%),late(80–100%)
Instruction density — too many must/never obligations
Instruction density — too many must/never obligations
A skill with many independent
must, never, ask, check, numbered steps, or nested conditionals requires the agent to satisfy all of them from memory. Omissions are invisible unless constraints are made checkable.Finding: instruction_density — score penalty: 14 pts.Remediation: Convert high-density constraints into rules, elicitations, checks, tests, and trace obligations in a skill.spec.yml.Research basis: Instruction following can be evaluated with checkable constraints; untestable instructions and missing proof surfaces are a risk signal (Zhou et al. 2023, IFEval).Undeclared dependencies
Undeclared dependencies
When the active body mentions tools, commands, installs, APIs, auth, env vars, or packages without a structured dependency declaration, the agent may choose unavailable tools or skip preflight without any evidence.Finding:
implicit_dependency_contract (implicit tool/dependency contract) — score penalty: 16 pts.Remediation: Add a skill.spec.yml with dependencies, commands.requires, and degraded proof policy.Missing proof and trace surfaces
Missing proof and trace surfaces
Without scenario tests, a trace configuration, or a
.skillspec evidence directory, there is no falsifiable record of whether the skill’s route choices and constraints held during a run.Research basis: Agent quality needs process evidence, not only final answers (AgentBoard, 2024). Focused skills with deterministic task-success checks outperform broad documentation (SkillsBench, 2025).
Risk score
Doctor produces two complementary numbers from the same penalty sum:
When a valid
skill.spec.yml is present, doctor also computes contract mitigation — how much the structured contract reduces raw prose risk:
Mitigation never reduces risk below zero and doesn’t erase activation risk, because the loaded
SKILL.md still competes for attention.
Shape detection
Before scoring, doctor classifies the target’s folder shape. This prevents a workspace from being scored as a single giant skill.
For workspace shapes, doctor emits one aggregate workspace risk report plus one package report per discovered
SKILL.md. Package identity — including plugin namespace — is preserved so scores don’t collapse across separate skills.
Output formats
--json format is stable enough for CI gates and dashboards. Every condition includes basis_ids, claim_scope, threshold_source, and machine-readable measurement fields.
Hosted page
Public skill URLs can be submitted to https://skillspec.sh/ for a hosted doctor report. The hosted page runs the same static analysis and produces a shareable risk summary without requiring a local install.Doctor is a static analysis tool. It does not simulate a specific model, inspect transformer attention weights, or observe actual agent runs. Its findings are directional risk signals backed by research on position effects, context load, instruction density, and proof gaps — not claimed runtime failure probabilities.