SkillSpec Commands, Dependencies, Artifacts, Recipes

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

Rules can route around unsafe commands. Commands must not route around rules.

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

The 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

The 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

The 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

The reference CLI directly checks 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 ] ;

When 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

The reference CLI validates recipe references but does not execute recipes. Execution remains the harness’s responsibility.

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?"

Keeping prose in snippets rather than in command templates or rule reasons means generated 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 ;

v0 keeps this section open because closure names are often product-specific. Closures are referenced from 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

The 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.

Get Started

Core Concepts

Guides

Spec Reference

SkillSpec Commands, Dependencies, Artifacts, Recipes

Commands

Safety Classes

Command Templates

Dependencies

Dependency Kinds

Checking Dependencies

Artifacts

Artifact Kinds

Recipes

Recipe Steps

Code Blocks

Snippets

Closures

Complete Command Example

​Commands

​Safety Classes

​Command Templates

​Dependencies

​Dependency Kinds

​Checking Dependencies

​Artifacts

​Artifact Kinds

​Recipes

​Recipe Steps

​Code Blocks

​Snippets

​Closures

​Complete Command Example

Commands

Safety Classes

Command Templates

Dependencies

Dependency Kinds

Checking Dependencies

Artifacts

Artifact Kinds

Recipes

Recipe Steps

Code Blocks

Snippets

Closures

Complete Command Example