Skip to main content
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.
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.
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.
Doctor also accepts a public GitHub URL so you can audit a skill before installing it. Use --markdown or --html to export the report.
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:
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.
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:
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:
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.