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.

Agent skills solved the discovery problem: a named 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:
It isIt is not
A contract that sits beside SKILL.md.A replacement for skills.
A CLI that scores, ports, compiles, and records.A new agent runtime or orchestration platform.
A way to make skills easier to compare across Codex, Claude, and Agents.A promise that every harness will behave identically.
A run record you can audit after the task.A security sandbox.
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 typical SKILL.md embeds its routing logic and safety rules in paragraphs: 
## Browser Research

Use this skill when the user wants to browse a URL, take a page snapshot,
click elements, or extract content from a live page.

For URL discovery you may use native search, but the final page evidence
must always come from the browser tool — never from a search-result summary.
Before inspecting a page, confirm which URL should be used.
The same intent expressed as a skill.spec.yml contract, using the before/after example from the SkillSpec repository: 
schema: skillspec/v0
id: example.browser_research
title: browser research
description: Route browser inspection tasks to browser automation and keep URL discovery separate from page evidence.

routes:
  - id: browser
    label: Browser automation
    rank: 10
  - id: native_search
    label: Native search for URL discovery
    rank: 20

rules:
  - id: browser_tasks_use_browser
    when:
      user_says_any:
        - browse
        - open
        - click
        - snapshot
        - inspect
        - extract from page
    prefer: browser
    forbid:
      - native_search_as_answer
    allow:
      native_search: url_discovery_only
    elicit:
      - target_url
    reason: Page evidence must come from observing the page, not from search-result summaries.

elicitations:
  target_url:
    question: Which URL should be inspected?
    choices:
      - id: user_provided_url
        label: Use the URL in the request
      - id: ask_for_url
        label: Ask for the URL
      - id: discover_url
        label: Search only to discover the URL
    default: ask_for_url
    max_choices: 1

trace:
  mode: event_log
  required: true
  record:
    - input_received
    - rule_matched
    - route_selected
    - elicitation_requested
    - outcome_recorded

tests:
  - name: browse task uses browser
    input: browse https://example.com and take a snapshot
    expect:
      route: browser
      forbid_exact:
        - native_search_as_answer
      elicit_exact:
        - target_url
      matched_rules_exact:
        - browser_tasks_use_browser
The prose 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us