Skip to main content

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.

Before you touch a skill — porting it, installing it, or handing it to an agent — it helps to know where the follow-through risk actually lives. skillspec doctor is a static analysis command that reads any skill folder or public GitHub URL and tells you exactly that: discovery risk, context load, buried obligations, undeclared dependencies, missing proof, and the likely consequence if an agent runs the skill as-is. No runtime, no code execution, just a fast read-only report you can act on.

​
Local Assessment

Point Doctor at any folder that contains a SKILL.md: 
skillspec doctor ./my-skill
The default output is a formatted terminal report. Here is a realistic example based on the README: 
SkillSpec Doctor
================
Target: ./my-skill        Shape: simple_skill

Agent follow-through risk: HIGH (74/100)

Findings
- description is short and generic -> automatic discovery may be unreliable
- active skill load is 8,482 tokens -> above the balanced target
- 14 must/never obligations appear after 60% of the body -> easy to miss
- tools and commands are used, but dependencies are never declared
- no tests and no progress/trace surface -> "done" can't be checked

Likely consequence
An agent may follow the broad task but skip a late safety gate, use an
undeclared tool, or claim completion without evidence.

Next step
Ask your agent: /skillspec import ./my-skill, compile it, test it, install it,
and print the alignment summary.
The risk score is the headline metric. A score of 74 out of 100 means high drift risk — not a grade of domain quality or author effort, just a measure of how likely an agent is to skip, reorder, or finish without proof.

​
Remote Assessment

Doctor accepts public GitHub URLs directly. You do not need to clone the repository first: 
skillspec doctor https://github.com/owner/repo/tree/main/skills/my-skill
Both tree/<branch>/... (canonical folder URL) and blob/<branch>/... styles are accepted when the path resolves to a folder rather than a single SKILL.md file. You can also pass a bare owner/repo shorthand to assess a repo root: 
skillspec doctor https://github.com/owner/repo
Remote targets are staged through a temporary partial sparse checkout and cleaned up after the report. Doctor never executes code from the target repository.

​
Output Formats

skillspec doctor ./my-skill
Human-readable report with shape contract, findings, likely consequence, and next step. Best for interactive review.
The --markdown, --html, and --json flags are mutually exclusive. Only one output mode can be active at a time.

​
Reading the Report

A Doctor report has four load-bearing sections:
Identifies what kind of skill folder was found: simple_skill, entry_skill_with_subskills, multi_skill_workspace, plugin_workspace, or non_skill_repository. The shape determines how the rest of the report is structured.For a simple_skill, the Shape Contract section also shows the detected kind, the kind-specific handling rule, analysis status, file count, and the next command implied by the shape gate — for example, skillspec import-skill for an un-ported prose skill.Multi-skill, entry-with-subskills, and plugin-shaped roots produce an aggregate workspace risk plus one package report per SKILL.md. Only non_skill_repository stops at the shape gate so Doctor does not spend work on ordinary code repositories.
A list of specific risk conditions, each with its measured value and the implication. Common findings include:
  • Description length and clarity — affects automatic discovery reliability
  • Active token load — above the balanced target increases the chance of mid-context misses
  • Obligation placement — must/never rules buried past 60 % of the body are easy to skip
  • Undeclared dependencies — tools and commands used but never declared
  • Missing trace or proof surface — "done" cannot be checked without a record
Each finding maps to published work on how agents fail: context-position effects, effective context limits, verifiable instruction following, and process-level evaluation. The report is explicit about what is measured versus what is a policy threshold.
A plain-language description of what a real agent run is likely to produce given the findings — not the best-case interpretation, but the realistic failure mode. For example: skipping a late safety gate, using an undeclared tool, or reporting completion without evidence.
The recommended action. For most skill-shaped targets this is an import and compile path. For workspace-shaped targets it may be skillspec workspace map first. For non-skill repositories Doctor stops at the shape gate.

​
Doctor Checklist

When you need a structured, step-by-step import guide rather than a free-form risk report, use the checklist subcommand: 
skillspec doctor checklist ./source-root --stage entry
The checklist names the activation policy, required commands, repeat-until loops, required evidence artifacts, and forbids such as no blind bulk promotion or plugin flattening. It is read-only and exits non-zero for non-skill sources. Use --stage entry to see the first-run checklist, --stage loop during iterative import work, and --stage exit to see the final gates before compile and install. 
skillspec doctor checklist ./source-root --stage loop
skillspec doctor checklist ./source-root --stage exit

​
Public Hosted Page

No install required for public skills. Paste any public GitHub skill URL into the hosted page: https://skillspec.sh/ The form validates the URL client-side and opens a prefilled GitHub issue. The report gallery on reports.html renders prior public reports without exposing a write token.

​
Automating Doctor in CI

You can request a public Doctor report by opening a Doctor report request issue with a public GitHub skill URL. GitHub Actions validates the target, stages the source, runs skillspec doctor, comments the Markdown report on the issue, and uploads Markdown, HTML, JSON, and text artifacts retained for 14 days. The workflow (doctor-report.yml) is recognized by either the doctor-report label or a title starting with Doctor report:. It rejects private repositories with local-run instructions so private source never appears in public Actions logs. For private skills or self-hosted CI, add Doctor to your own pipeline: 
skillspec doctor ./skills/my-skill
skillspec doctor ./skills/my-skill --markdown >> "$GITHUB_STEP_SUMMARY"
skillspec doctor ./skills/my-skill --json > artifacts/doctor-report.json
Use --json when you need machine-readable output in scripts or custom dashboards. The JSON report preserves the full structural_score and score_model fields that the terminal and Markdown renderers condense into the headline risk rating. Pipe it through jq to extract specific findings or threshold-check the score in CI.

Build docs developers (and LLMs) love

Get started for freeTalk to us