SKILL.md with a short description gives a harness something to route to. But once a skill activates, it is a prompt again — and prompts are unreliable, unenforced, and invisible after the run. Critical rules are buried at line 400 where attention fades. Every failure becomes another paragraph, which makes the next miss more likely. And when the agent says “done,” there is no record of which steps actually ran.
SkillSpec closes that gap. It is a small skill.spec.yml that lives next to your SKILL.md and holds the load-bearing parts of your skill in a form a validator, a test runner, and a trace can all understand — routes, rules, forbidden actions, dependencies, elicitations, and proof expectations. Your prose stays exactly where it is.
What SkillSpec Is — and Is Not
Before going further, here is a plain account of the boundaries:
Enforcement of tool boundaries is still the harness’s job. SkillSpec makes a run auditable: you can see what was claimed and check it against the contract.
Four Key Capabilities
Doctor Risk Reports
Point Doctor at any skill — a local folder or a public GitHub URL — and get a scored risk report: discovery reliability, context load, buried obligations, undeclared dependencies, and the likely consequence for agent follow-through.
Structured Contracts
A
skill.spec.yml captures typed routes, rules, forbidden actions, dependencies, and elicitations beside your existing SKILL.md. A JSON Schema and Rust type model back every field — nothing is a free-text convention.Import and Porting
skillspec port-one-shot reads a prose skill and generates a full contract: routes, rules, dependencies, checks, and proof expectations. Uncertain mappings are marked review_required so nothing is silently invented.Traces and Alignment Proof
Every run can leave an alignment summary: selected route, completed steps, missing proof, forbidden-action status, and token metrics. Not just “done” — a record you can inspect and publish alongside the skill.
The Core Premise: Keep the Prose. Structure the Decisions.
SkillSpec does not argue that prose is bad. Prose is the right medium for tone, context, domain judgment, examples, and human explanation. The problem is that critical behavior often hides inside paragraphs: route choices, forbidden substitutions, dependency assumptions, elicitation points, safety rules, and success conditions. This follows the same broad lesson that made OpenAPI useful for REST APIs: formal descriptions reduce guesswork and enable code, docs, tests, and review to share one contract. SkillSpec applies that lesson to skills. Keep prose for the parts that require judgment. Move the parts that require proof into a form that validators, test runners, and traces can understand.Before and After
A typicalSKILL.md embeds its routing logic and safety rules in paragraphs:
skill.spec.yml contract, using the before/after example from the SkillSpec repository:
SKILL.md stays in place for the agent to read. The contract lives beside it for validators, test runners, and traces to check.
Ready to Try It?
Run Doctor on any skill in 30 seconds — no account required.Quickstart →
Install SkillSpec, run your first Doctor risk report, and port a skill to a structured contract in five minutes.