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.

SkillSpec has two moving parts: the CLI binary that scores, validates, ports, and records, and a small harness plugin that lets your agent drive those commands from chat. Follow the steps below and you will have a Doctor report, a passing contract, and your first alignment proof before the coffee cools.
1

Install the CLI

The fastest path is the release installer. It downloads the right binary for your platform, verifies the SHA256 checksum, and writes the binary to ~/.local/bin.
curl -fsSL https://skillspec.sh/install.sh | sh
skillspec --version
On unsupported platforms (e.g. Linux ARM), fall back to cargo install skillspec. The Cargo path builds from source and works anywhere Rust is installed.
2

Install the harness plugin

The harness plugin lets you invoke SkillSpec commands from within Claude Code or Codex using natural-language requests like /skillspec run doctor on ./my-skill. Install it for whichever harness you use.
claude plugin marketplace add modiqo/skillspec --sparse .claude-plugin plugins/skillspec
claude plugin install skillspec@skillspec
claude plugin list
3

Run Doctor on a skill

Point Doctor at any skill directory. You get a risk score, a list of findings, and a clear next step — no account or sign-in required.
skillspec doctor ./my-skill

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.
Doctor also accepts a public GitHub URL so you can audit a skill before installing it. Use --markdown or --html to export the report.
skillspec doctor ./my-skill --markdown > skillspec-doctor.md
skillspec doctor ./my-skill --html    > skillspec-doctor.html
4

Validate and test

Once a skill.spec.yml exists — either hand-authored or ported in the next step — run the four-command adoption gate to confirm it is ready to rely on:
skillspec validate skill.spec.yml
skillspec imports check skill.spec.yml
skillspec test skill.spec.yml
skillspec deps check skill.spec.yml
All four commands must pass before a skill is considered production-ready. validate checks the schema and internal references. imports check verifies that every referenced resource is reachable. test runs the inline behavioral test cases. deps check confirms that declared dependencies exist in the current environment.
You can also run skillspec decide skill.spec.yml --input='<user task>' --trace-dir .skillspec/traces to inspect a route decision outside of a live harness session.
5

Port to a contract

port-one-shot reads a prose skill and generates a full skill.spec.yml — routes, rules, elicitations, dependencies, checks, and proof expectations — in one pass. Uncertain mappings are flagged review_required rather than silently invented.
skillspec port-one-shot ./my-skill \
  --out ./my-skill-spec \
  --target codex-skill \
  --prove
The --prove flag runs the inline tests and emits an alignment summary after generation so you can see immediately whether the contract captures the skill’s intended behavior.Or ask your agent to do the full import loop from chat:
/skillspec import ./my-skill, compile it, test it, install it, and print the alignment summary.
6

Verify the alignment proof

After a run, check that the trace aligns with the contract. Pass the spec path and the decision trace directory written by the run:
skillspec trace align ./skill.spec.yml \
  --decision-trace .skillspec/traces/run-123
The output shows the selected route, completed steps, any missing proof, forbidden-action status, and token metrics. Publish this alongside the skill and your skill.spec.yml so reviewers can see both the original Doctor score and the proof after porting.
SkillSpec makes a run auditable, not sandboxed. Enforcement of tool boundaries is still the harness’s job. The alignment summary tells you what was claimed; review it against what you expected.
The steps above use the release installer and plugin marketplace. For pinned versions, Git main builds, local checkouts, Windows binaries, SHA256 verification details, and the Justfile development workflow, see the Installation page.

Build docs developers (and LLMs) love

Get started for freeTalk to us