Documentation Index
Fetch the complete documentation index at: https://mintlify.com/modiqo/skillspec/llms.txt
Use this file to discover all available pages before exploring further.
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
| Flag | Description |
|---|---|
<target> | Local folder path, public GitHub tree/<branch>/... URL, blob/<branch>/... URL, or owner/repo shorthand. |
--json | Emit full machine report including structural_score and score_model. Mutually exclusive with --html and --markdown. |
--html | Emit a self-contained review page. Mutually exclusive with --json and --markdown. |
--markdown | Emit GitHub-flavored Markdown for run summaries and issue comments. Mutually exclusive with --json and --html. |
doctor checklist options
| Flag | Description |
|---|---|
<source> | Local folder, public GitHub URL, or shorthand. Same target types as doctor. |
--stage entry|loop|exit | Which checklist stage to emit. Defaults to entry. |
--json | Emit checklist as JSON. |
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 thanSKILL.md. - Owner/repo shorthand —
owner/repoorowner/repo/path.
Shape detection
doctor detects one of five shape kinds and tailors the report accordingly:
| Shape | Description |
|---|---|
simple_skill | A single atomic SKILL.md package. Receives full source-map structural scoring plus frontmatter discovery and agent drift risk. |
multi_skill_workspace | A root with multiple SKILL.md packages. Receives aggregate workspace risk plus one package report per SKILL.md. |
plugin_workspace | A plugin-shaped root with a skills/ directory and plugin metadata. Preserves plugin namespaces; reports namespace-level risk. |
entry_skill_with_subskills | An entry skill that references additional subskill packages. |
non_skill_repository | An ordinary code repository with no SKILL.md. Shape-only report; no structural scoring. |
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_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: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.Related commands
skillspec source stage <uri>— Stage a public GitHub source before doctor for explicit candidate inspection.skillspec import-skill <path>— Draft askill.spec.ymlfrom a single prose SKILL.md after doctor confirms asimple_skillshape.skillspec workspace map <source-root>— Map a multi-skill or plugin workspace after doctor identifies the shape.