Skip to main content
skillspec doctor is a read-only diagnostic that assesses agent follow-through risk for any SKILL.md skill source. It accepts local folders, public GitHub skill folder URLs, and public GitHub repo URIs. The report treats risk as the headline metric so users do not misread structural scoring as a grade of domain quality. Remote targets are staged through a temporary partial sparse checkout and cleaned up after the report. In the harness, assess skill maps to this read-only path and must stop after the report unless the user also explicitly asks to import or install.

​
Synopsis

​
Options

​
doctor checklist options

​
Target types

  • Local folder — A directory path. Can be a single skill folder or a multi-skill workspace root.
  • GitHub tree URL — https://github.com/<owner>/<repo>/tree/<branch>/<path> (canonical GitHub folder shape).
  • GitHub blob URL — https://github.com/<owner>/<repo>/blob/<branch>/<path> accepted when the path resolves to a folder rather than SKILL.md.
  • Owner/repo shorthand — owner/repo or owner/repo/path.

​
Shape detection

doctor detects one of five shape kinds and tailors the report accordingly:

​
Report sections

The default terminal report includes:
  • What this measures — a plain-language description of the risk model.
  • Shape Contract — detected kind, kind-specific handling rule, analysis status, skill-file count, package count, namespace count, plugin-root details, referenced skill paths, and next command implied by the shape gate.
  • Surface — visible skill activation metadata.
  • Findings — specific risk indicators and structural observations.
  • Likely Consequence — what agent drift risks the findings imply.
  • Next Step — actionable remediation or porting guidance.
  • Basis Summary — scoring basis and model.
Workspace reports also include workspace_identity with total source files, namespaced package count, namespace count, unique byte-identical SKILL.md content count, repeated content groups/occurrences, repeated frontmatter names, estimated copied-vs-referenced source tokens, and source_content_refs.

​
Examples

Assess a local skill folder:
Assess a public GitHub skill folder and emit a Markdown report:
Assess a GitHub repo and capture JSON output for CI:
Run a shape-specific import checklist for the entry stage:

​
doctor checklist

doctor checklist runs the same source-shape inspection as doctor and emits a shape-specific checklist for single SKILL folders, multi-skill roots, entry skills with subskills, plugin-shaped workspaces, or non-skill repositories. The checklist names activation policy, commands, repeat-until loops, required evidence, and forbids such as no blind bulk promotion or plugin flattening. It is read-only and exits non-zero for non-skill sources.
Output formats --json, --html, and --markdown are mutually exclusive. The JSON output preserves structural_score and score_model fields that are omitted from human-readable formats to avoid misinterpretation.
  • skillspec source stage <uri> — Stage a public GitHub source before doctor for explicit candidate inspection.
  • skillspec import-skill <path> — Draft a skill.spec.yml from a single prose SKILL.md after doctor confirms a simple_skill shape.
  • skillspec workspace map <source-root> — Map a multi-skill or plugin workspace after doctor identifies the shape.