SkillSpec: a contract layer for SKILL.md files that agents keep ignoring
SkillSpec makes agent skills followable, testable, and provable with Doctor risk reports, guided imports, structured contracts, and alignment proof.
At a glance
- What is it?
- SkillSpec is a Rust CLI that scores a SKILL.md for agent follow-through risk and then compiles it into a structured skill.spec.yml contract. It is a diagnostic and specification tool, not a new agent runtime, and its value depends entirely on whether you treat the Doctor score as a signal rather than a verdict.
- Who is it for?
- SkillSpec is worth adopting if you maintain SKILL.md files that carry safety gates, forbidden actions, or declared dependencies, and you want those obligations represented outside prose before an agent runs. Skip it if your skills are throwaway prompts with no compliance surface: the contract and the Doctor report add a file to maintain for no benefit.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 38 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure mode SkillSpec is built around
A SKILL.md is text. The harness loads it and the model reads whatever portion of the context it attends to. The README states the problem directly: models are most reliable at the start and end of context, not the middle, so a never-do-X rule sitting at line 400 is structurally easy to skip. The project also names a second-order effect that is easy to miss in practice. Every observed failure tends to become another paragraph in the skill file, which lengthens the document and makes the next miss more likely. The prose grows as a response to the problem it is causing.
The third complaint is about evidence. After a run you see the final answer, not which route executed, which steps happened, or what was skipped. SkillSpec targets that gap by moving the load-bearing parts of a skill out of prose and into a small structured contract: when to use the skill, which route to take, what is forbidden, what dependencies must exist, what checks must pass, and what proof should exist at the end. That list is the project's own framing of what belongs in the contract rather than the narrative.
The audience follows from this. Anyone writing a throwaway skill is not the target. The target is a team that depends on a skill whose failure is expensive: a safety gate that must fire, a tool that must not be called, a completion claim that needs backing.
What Doctor actually reports
The entry point is a single command against a local folder or a public GitHub URL. The README gives this example:
skillspec doctor ./my-skill
The printed report names the target and classifies its shape (the example shows simple_skill), then assigns a follow-through risk band with a numeric score. In the sample output the band is HIGH at 74/100. The findings below the score are the substantive part, and they are specific enough to act on: a description judged short and generic, an active skill load of 8,482 tokens described as above the balanced target, fourteen must/never obligations appearing after 60 percent of the body, tools and commands used but dependencies never declared, and no tests or progress surface.
The report then states a likely consequence in plain language (an agent may follow the broad task but skip a late safety gate, use an undeclared tool, or claim completion without evidence) and a next step phrased as a prompt to hand your agent: /skillspec import ./my-skill, compile it, test it, install it, and print the alignment summary.
Two things about this deserve scrutiny. First, the score is a heuristic over document structure, not a measurement of model behaviour. A 74 does not mean the agent fails 74 percent of the time. Treat the findings as the signal and the number as a summary of them. Second, several findings are structural and cheap to fix (declare the dependencies, move the obligations earlier, add a trace surface), which is what makes the report useful even if you never adopt the contract format.
The contract format and the import loop
The structured side of the tool is a file named skill.spec.yml that lives next to your SKILL.md. The README does not reproduce the schema in the material available here, so the exact keys are something to read from the repository rather than assume. What the material does establish is the division of labour: the spec carries the use conditions, the route, the prohibitions, the required dependencies, the checks, and the expected proof, while the SKILL.md keeps the explanatory prose.
The README labels the workflow as a loop, shown truncated as Assess -> Port -> and cut off at that point. The Doctor command is the assess stage. The import path appears in the suggested next step as /skillspec import ./my-skill, followed by compile, test, install, and an alignment summary. That sequence is the project's claim to being more than a linter: the spec is compiled, tested, installed into a harness, and then reported on.
The alignment summary is the piece that addresses the third complaint from the README. A record you can inspect at the end is the difference between a skill that reports done and a skill that can show which route ran and which checks passed. Because the material does not include a sample alignment summary, the granularity of that record is unverified here.
Installing the CLI and the harness plugin
Two install paths are documented. The shell installer pulls a release artifact and verifies its checksum, writing to ~/.local/bin by default:
curl -fsSL https://skillspec.sh/install.sh | sh skillspec --version
Or through Cargo:
cargo install skillspec skillspec --version
Version and destination can be pinned through environment variables passed to the installer, which the README shows as SKILLSPEC_VERSION and SKILLSPEC_INSTALL_DIR. Prebuilt archives exist for macOS, Linux x86_64, and Windows x86_64, each with a .sha256 checksum that the installer checks. Unreleased main is installable with cargo install --git pointed at the repository, and a local checkout with cargo install --path crates/skillspec-cli --force.
The CLI alone does not wire anything into an agent. That is a separate plugin step. For Claude Code the documented commands are claude plugin marketplace add modiqo/skillspec --sparse .claude-plugin plugins/skillspec, then claude plugin install skillspec@skillspec, then claude plugin list to confirm. For Codex the equivalent is codex plugin marketplace add modiqo/skillspec --ref main --sparse .agents --sparse plugins/skillspec followed by codex plugin add skillspec@skillspec.
For local work the repository ships a skill folder that can be installed directly into a harness with skillspec install skill skills/skillspec --target <codex|agents|claude-local> --retire-existing. The --retire-existing flag is worth noticing: it implies the installer manages prior installations rather than leaving duplicates behind.
The Justfile and what preflight does not cover
The repository uses a Justfile to keep the crate split and the local harness install flow in one place. Documented recipes include just packages to show the crate hierarchy and dependency direction, just build-debug and just build-release, just install-debug and just install-release for installing the checkout as the active local CLI, just install-targets to list detectable harness roots, and just install-skill with a target or just install-skill-all. There is also just dev-install-all, which the README describes as a debug build, debug CLI install, and skill installs across every detected harness.
One recipe is explicitly opt-in and unusual: just harness-lab-live-durable-rote-exec copies an authenticated rote binary and ~/.rote config into a lab, excluding workspaces, to prove that one command uses rote exec --. That is a narrow, environment-dependent proof rather than part of the normal test path, and it requires credentials you may not want in a lab directory.
just preflight is the local gate before pushing. The README is explicit that it uses plain Cargo commands rather than an extra dependency, and that it runs formatting, locked workspace check, clippy, tests, package file-list checks for every split crate, example validation and tests, and conformance fixture checks. There is a documented gap: PR CI uses package file-list checks instead of cargo publish --dry-run, because a same-version split crate graph cannot dry-run downstream crates until their sibling dependencies already exist on crates.io. Tagged releases publish the crates in dependency order. If you fork this project and change the workspace, that publish ordering constraint is the thing most likely to bite you, not the test suite.
Where SkillSpec is the wrong tool
The honest limitation is stated in the README itself: for a throwaway skill, loading text and hoping is fine. SkillSpec adds a second file per skill and a compile, test, install cycle. If your skills are short prompts with no forbidden actions, no dependencies to declare, and no completion claim anyone audits, the contract is overhead with no corresponding risk reduction.
There is a sharper boundary. The Doctor report judges the document, not the model. A skill can score well structurally and still be followed badly by a particular model at a particular context length, and a skill can score badly while working fine in practice because the harness truncates or reorders context in ways the audit does not model. Nothing in the supplied material describes per-model calibration, so the score should be read as a structural audit rather than a prediction.
The token-load finding illustrates the tension. The sample flags 8,482 active tokens as above a balanced target, but the target itself is not defined in the material. A large skill may be large for good reason, and splitting it to satisfy the audit could make routing worse. Treat that finding as a prompt to examine the skill, not as an instruction.
Finally, the alignment proof depends on the harness plugin being installed and on the skill being run through the compiled path. A skill invoked outside that path produces no record, so the evidence story is only as complete as your team's discipline about which skills go through the loop.
How this differs from prose-only skill authoring
The obvious alternative is doing nothing beyond writing a careful SKILL.md: keep the obligations near the top, keep the file short, declare dependencies in the text, and hope the model attends to them. That approach costs nothing and works often. Its weakness is exactly what the README describes: there is no artifact to inspect after a run, and the only feedback loop is a human noticing that a rule was skipped and adding another paragraph.
A second alternative is a full orchestration framework that owns the agent loop, the tool routing, and the trace. Those systems give you a durable record because they control execution. SkillSpec deliberately does not go there. The README is explicit about the constraint: no new agent runtime, no orchestration platform, just a CLI and a small skill.spec.yml next to your SKILL.md. The trade is real. You keep your existing harness and your existing skills, and in exchange you get an audit and a contract rather than an execution engine. If your problem is that you cannot see what the agent did at all, a runtime with tracing solves more than SkillSpec does. If your problem is that a specific skill's rules are not being honoured, the contract approach is the smaller intervention and it does not require migrating anything.
Version cadence, licence, and what to check first
The project is licensed Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That is a permissive licence, not a copyleft one, so embedding the CLI in an internal pipeline does not create source-disclosure obligations. This is a description of the licence text, not legal advice; if you redistribute a modified binary, read the NOTICE and attribution requirements in the licence yourself.
The release history shows three versions in roughly two weeks in late July 2026: v0.2.0, v0.2.1, and v0.2.2, with the last push to main in early August 2026. That cadence is fast for a tool whose output you might gate a release on, and it means the skill.spec.yml schema and the Doctor scoring heuristics are both plausibly still moving. Pin a version through SKILLSPEC_VERSION in CI rather than tracking latest, and re-run the audit after upgrading, because a scoring change can turn a passing skill into a flagged one without any change on your side.
There is no stated long-term support policy or schema stability guarantee in the material, so treat the spec format as pre-1.0. Before adopting it for a skill that matters, run skillspec doctor against that skill, read the findings against failure modes you have already observed, and only then decide whether the contract format earns its place next to the SKILL.md.
Editorial conclusion
SkillSpec is worth adopting if you maintain SKILL.md files that carry safety gates, forbidden actions, or declared dependencies, and you want those obligations represented outside prose before an agent runs. Skip it if your skills are throwaway prompts with no compliance surface: the contract and the Doctor report add a file to maintain for no benefit. Before trusting it, run skillspec doctor on one skill whose failure modes you already know and check whether the findings match reality; the tool's usefulness rests on that calibration, not on the score itself.
Community notes