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.
Commands are instructions, not implicit permission to execute. A command template tells a harness or agent what invocation to consider; the harness still applies its own safety and approval policy before anything runs. Dependencies are contracts, not grants — declaring a cli dependency does not install it, and declaring a local_write safety class does not authorize the mutation. Both constructs exist to make the skill’s assumptions explicit and inspectable.
Commands
Commands are named instruction templates. They belong in the commands mapping and are referenced by states, rules (after_success), recipes (run_command), and route checks.
command = [ "description" ":" string ] ,
"template" ":" string ,
[ "safety" ":" safety-class ] ,
[ "requires" ":" command-requires ] ,
[ "parse" ":" mapping-of identifier to string ] ,
[ "success_when" ":" mapping ] ;
| Field | Required | Notes |
|---|
template | ✅ | The instruction string. Not a shell command — see Command Templates. |
description | — | Human-readable description of what the command does. |
safety | — | Declares the safety class of the action. See Safety Classes. |
requires.dependencies | — | Dependency ids that must be present before this command runs. |
requires.resources | — | Resource ids whose content the command references. |
requires.files | — | File paths that must exist on the local filesystem. |
requires.env | — | Environment variable names that must be set. |
requires.auth | — | Auth token or credential names required. |
parse | — | Output parse hints: a mapping of identifier to extraction expression. |
success_when | — | Open mapping describing success conditions. Harness-specific. |
Safety Classes
Safety class is a declaration, not enforcement. It gives the harness a concrete pre-tool-call classification.
| Safety Class | Meaning |
|---|
read_only | Safe to run automatically when dependencies are present |
local_read | Reads local workspace state; should stay inside the chosen working directory |
local_write | Writes to the local filesystem; harness should confirm scope |
network_read | May use authenticated network state; should preserve response provenance |
network_write | Writes to a remote system; requires explicit approval |
browser_attach | Depends on live user session state; ask before attaching or opening a browser |
credential_request | Must stay visible and bounded; credentials must not be inlined |
destructive | Requires explicit user approval before execution |
Command Templates
template is a string pattern, not a shell command. v0 does not mandate a template engine. Implementations should treat the template as a concrete example unless they explicitly support rendering with a variable substitution syntax.
commands:
validate_spec:
description: Validate the skill.spec.yml against the embedded schema.
template: "skillspec validate skill.spec.yml"
safety: read_only
requires:
dependencies:
- skillspec_cli
collect_trace_cost:
description: Collect trace cost and context-window spend after a run.
template: "rote trace --deps --format json"
safety: local_read
requires:
dependencies:
- rote_cli
Command templates are the unit that compilers and generated SKILL.md loaders render into harness-readable instructions. Keep templates concrete and self-contained. Variable placeholders, if used, should follow a convention your harness understands.
Dependencies
Dependencies declare tools, files, environment variables, services, adapters, browsers, or packages needed by commands or routes. They belong in the top-level dependencies mapping and are referenced by commands, code blocks, recipes, and dependency provision elicitations.
dependency = "kind" ":" dependency-kind ,
[ "description" ":" string ] ,
[ "command" ":" string ] ,
[ "path" ":" string ] ,
[ "env" ":" string ] ,
[ "check" ":" dependency-check ] ,
[ "permission" ":" dependency-permission ] ,
[ "provision" ":" dependency-provision ] ;
Dependency Kinds
| Kind | What It Represents | CLI-Checkable |
|---|
cli | A command-line tool expected on PATH | ✅ |
file | A required local file | ✅ |
env | A required environment variable | ✅ |
package | A language-level package (npm, cargo, pip, etc.) | Harness |
service | A running external service | Harness |
adapter | A named harness adapter or integration | Harness |
browser | A browser instance or automation context | Harness |
check sub-field describes how to determine presence:
dependencies:
skillspec_cli:
kind: cli
description: The skillspec CLI, required for validation and testing.
check:
command: skillspec --version
permission sub-field describes whether use needs user approval:
dependencies:
browser_session:
kind: browser
description: Active browser session for page observation.
permission:
required: true
reason: Attaching to an active session accesses live user state.
safety: browser_attach
provision sub-field describes install or connection options that must be selected through elicitation before mutation:
dependencies:
rote_cli:
kind: cli
description: The rote durable executor CLI.
provision:
elicit: install_rote
options:
- id: install_via_cargo
label: Install with cargo
command: "cargo install rote"
safety: local_write
- id: install_via_brew
label: Install with Homebrew
command: "brew install rote"
safety: local_write
Checking Dependencies
# Check all declared dependencies
skillspec deps check ./skill.spec.yml
# Check dependencies for a specific command only
skillspec deps check ./skill.spec.yml --command validate_spec
cli, file, and env dependencies. package, service, adapter, and browser dependencies are reported as requiring harness-level checks.
Artifacts
Artifacts name the files or data products that commands, code blocks, and recipes consume or produce. They make dataflow explicit without requiring a workflow engine.
artifact = "kind" ":" artifact-kind ,
[ "description" ":" string ] ,
[ "path" ":" string ] ,
[ "schema" ":" value ] ,
[ "produced_by" ":" sequence-of executable-ref ] ,
[ "consumed_by" ":" sequence-of executable-ref ] ;
Artifact Kinds
| Kind | Description |
|---|
file | A single file on the local filesystem |
directory | A directory tree |
json | A structured JSON data product. May include an optional schema field. |
text | Plain text output |
image | An image file (screenshot, diagram, export) |
pdf | A PDF document |
transcript | A session transcript or conversation log |
report | A structured or prose report document |
produced_by and consumed_by take executable refs only. Valid kind values are command, code, and recipe. Routes and rules can require checks, schedule recipes, or reference imports and resources, but they are not artifact producers or consumers.
artifacts:
validation_report:
kind: json
description: Machine-readable validation result from skillspec validate.
produced_by:
- kind: command
id: validate_spec
consumed_by:
- kind: recipe
id: generate_proof
Recipes
Recipes are structured procedures — especially useful for multi-step workflows where the order and conditions of import loading, command execution, and artifact production matter.
recipe = [ "description" ":" string ] ,
[ "ordered" ":" boolean ] ,
[ "requires" ":" recipe-requires ] ,
[ "steps" ":" sequence-of recipe-step ] ;
ordered is true, the harness should execute steps in sequence. When false or absent, the harness may choose execution order.
Recipe Steps
Each step is a single-key object naming the step kind and its target id:
| Step kind | Purpose |
|---|
load_import: <import-id> | Load a declared import into context |
load_resource: <resource-id> | Load a declared resource |
run_command: <command-id> | Execute a declared command |
run_code: <code-id> | Execute a declared code block |
produce_artifact: <artifact-id> | Signal that the next step should produce this artifact |
consume_artifact: <artifact-id> | Signal that the next step consumes this artifact |
ask: <elicitation-id> | Ask a bounded user question |
branch: {if, then, otherwise} | Conditional branch to another step id |
note: <string> | A human-readable annotation in the procedure |
recipes:
run_and_validate:
description: Load policy, validate the spec, and produce a report.
ordered: true
requires:
imports:
- shared_policy
dependencies:
- skillspec_cli
steps:
- load_import: shared_policy
- note: Validate the spec before generating any output.
- run_command: validate_spec
- produce_artifact: validation_report
- branch:
if: validation_passed
then: generate_proof
otherwise: report_errors
Code Blocks
Code blocks preserve executable knowledge extracted from source material or written inline. They live in the top-level code mapping.
code-block = "language" ":" string ,
"kind" ":" code-kind ,
"source" ":" code-source ,
[ "provenance" ":" code-provenance ] ,
[ "purpose" ":" string ] ,
[ "requires" ":" code-requires ] ,
[ "inputs" ":" sequence-of artifact-id ] ,
[ "outputs" ":" sequence-of artifact-id ] ,
[ "safety" ":" code-safety ] ,
[ "use_when" ":" sequence-of string ] ;
source is either inline YAML (source.inline: |) or a file reference (source.file: path/to/script.sh). Code safety uses a separate sub-object with boolean flags (mutates_input, writes_files, network) rather than the string safety class used by commands.
A fenced code block extracted from a prose skill is not automatically safe to run just because it is represented in the spec. Importers should preserve code as example kind first and only promote to runnable_script after explicit review.
Snippets
Snippets carry prose that should remain prose: questions, user-facing copy, completion prompts, or short explanations. They belong in the top-level snippets mapping and are referenced by states.
snippet = "text" ":" string ;
snippets:
task_entry:
text: "What would you like to do today?"
completion_prompt:
text: "The task is complete. Would you like me to remember this workflow for next time?"
SKILL.md loaders can stay small without losing product voice. It also makes user-facing copy reviewable and testable independently of routing logic.
Closures
closures is an open mapping for post-task behavior. Common closure names describe actions like summarizing cost, writing a digest, asking to remember, or asking to share with a team.
closures = "closures" ":" mapping ;
Rule.after_success, which ties them to the rule that made them necessary:
rules:
- id: recurrence_likely_schedule_closures
when:
task_recurrence_likely: true
after_success:
- collect_trace_cost
- ask_to_remember
closures:
collect_trace_cost:
description: Collect trace cost and context-window spend.
ask_to_remember:
description: Ask whether to remember this route for future similar tasks.
Complete Command Example
The following shows a command with a safety class, dependency requirement, and parse hints:
dependencies:
skillspec_cli:
kind: cli
description: The skillspec CLI.
check:
command: skillspec --version
commands:
validate_spec:
description: Validate skill.spec.yml and emit JSON results.
template: "skillspec validate skill.spec.yml --json"
safety: read_only
requires:
dependencies:
- skillspec_cli
files:
- skill.spec.yml
parse:
error_count: "$.errors | length"
warning_count: "$.warnings | length"
success_when:
exit_code: 0
safety: read_only declaration tells the harness this command reads without mutating state. The requires block declares that skillspec_cli must be present and skill.spec.yml must exist before the command can run. parse provides extraction hints a harness can use to pull structured values from command output without needing to re-parse the raw text.