SkillSpec v0 JSON Schema: Types and Validation Rules

The JSON Schema for skill.spec.yml is embedded in the CLI binary and covers every v0 construct. It enforces typed fields, required properties, and additionalProperties: false on every typed object — unknown fields are not warned about, they are invalid. The schema is the machine-readable companion to the Grammar Reference.

Getting the Schema

Print the embedded schema to a file with:

skillspec grammar schema --json > skill.spec.schema.json

You can then use it with any JSON Schema validator, wire it into your editor for YAML completion, or reference it in CI:

# Example: validate with ajv-cli
ajv validate -s skill.spec.schema.json -d skill.spec.yml

The schema $id is https://skillspec.dev/schemas/skill.spec.v0.json and targets JSON Schema draft 2020-12.

Strict Validation

Every typed object in the schema sets "additionalProperties": false. This means:

A field spelled prefr instead of prefer fails validation immediately.
A field spelled forbit instead of forbid fails validation immediately.
A field spelled elicitations at a route level (where it does not belong) fails validation immediately.

Without this strictness, misspelled behavior silently disappears: skillspec validate passes, the rule evaluates, but the misspelled effect never fires. Strict schema rejection turns silent data loss into an auditable error.

Explicit extension surfaces — metadata, allow values, choice sets, artifact schema, command success_when, and closures — use additionalProperties: true because they are intentionally open mappings.

Type Overview

Type	Description
`SkillSpec`	Root document object. Requires `schema`, `id`, `title`, `description`.
`Route`	A candidate way to satisfy work. Requires `id` and `label`.
`Rule`	A steering decision. Requires `id`. All other fields are optional.
`Elicitation`	A bounded question. Requires `question` and `choices`.
`Dependency`	A declared tool, file, env var, service, adapter, or browser requirement. Requires `kind`.
`Import`	A runtime-loadable Markdown file. Requires `path` and `role`.
`Resource`	Provenance or supporting source material. Requires `path` and `role`.
`CodeBlock`	Executable knowledge preserved from source or inline. Requires `language`, `kind`, and `source`.
`Artifact`	A named data product. Requires `kind`.
`Recipe`	A structured procedure composed of ordered steps.
`State`	A named lifecycle position.
`Command`	An instruction template with safety class. Requires `template`.
`Snippet`	User-facing prose. Requires `text`.
`Test`	A scenario contract. Requires `name`, `input`, and `expect`.
`Proof`	Aggregate confidence metrics.

Safety Classes

The safety_class enum appears on commands, elicitation choices, and dependency permission and provision fields. It is a declaration for the harness — not an execution permission.

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; should 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

Dependency Kinds

Kind	What It Represents
`cli`	A command-line tool expected on `PATH`. Directly checkable by the reference CLI.
`package`	A language-level package (npm, cargo, pip, etc.). Harness-specific check.
`file`	A required local file. Directly checkable by the reference CLI.
`env`	A required environment variable. Directly checkable by the reference CLI.
`service`	A running external service. Harness-specific check.
`adapter`	A named harness adapter or integration. Harness-specific check.
`browser`	A browser instance or automation context. Harness-specific check.

The reference CLI can directly check cli, file, and env dependencies via skillspec deps check. package, service, adapter, and browser dependencies are harness-specific and are reported as requiring harness-level checks.

Import Roles

Role	When to Use
`policy`	Shared operating rules that apply before any task action. Use `load: always`.
`reference`	Branch-specific reference material loaded when a particular route or recipe is active.
`procedure`	Step-by-step guidance for a task path. Connected via `used_by` or `requires.imports`.
`example`	Worked examples of correct behavior. On-demand; connected to code or recipe.
`skill`	Another skill document loaded as active guidance during a run.

Resource Roles

Role	When to Use
`source_material`	Original prose skill or evidence document preserved for provenance.
`reference`	Supporting reference file that is not loaded as runtime guidance.
`required_procedure`	A procedure document that must be consulted but is not a runtime import.
`example`	Example output, fixture, or evidence that supports code provenance.
`script`	A script file referenced by a code block or recipe.
`asset`	Any other supporting file (image, data, template) needed by the skill.

Code Kinds

Kind	Meaning
`example`	Illustrative code; not expected to be run automatically.
`runnable_script`	Reviewed and approved for execution through a recipe or command.
`probe`	A lightweight inspection script; reads state without mutating it.
`transform`	A data transformation that consumes and produces artifacts.
`validator`	A check script that asserts correctness of a condition or artifact.
`troubleshooting`	Diagnostic code to run when a route or command fails.
`reference`	Code preserved for documentation purposes only.

Artifact Kinds

Kind	Meaning
`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.

Cross-Reference Rules

skillspec validate enforces reference closure across the entire document. The most important rules:

Routes and Rules

Every Rule.prefer must reference an existing Route.id
Every Rule.route_order item must reference an existing Route.id
Every Rule.elicit item must reference an existing elicitation id
Every Rule.after_success item must reference an existing command or closure id
Every Test.expect.route must reference an existing Route.id

Elicitations

Every Elicitation.default must reference one of its own choices
Every Elicitation.required_when.route must reference an existing route
Every ElicitationChoice.route must reference an existing route
Every ElicitationChoice.next must reference an existing state

Imports and Resources

Every Import.requires.imports item must reference an existing import id
The import dependency graph must be acyclic
Every on_demand import must be connected via used_by, requires.imports, a code block, a recipe, or a load_import step
Every resource must be referenced by code or recipe, or declare used_by

Code Blocks

Code.provenance must declare exactly one of resource or import
Every Code.requires.* item must reference an existing id of the appropriate kind
Every Code.inputs and Code.outputs item must reference an existing artifact

Artifacts and Recipes

Every produced_by and consumed_by reference must use kind command, code, or recipe
Every recipe step reference must point at an existing id
Every scenario test must declare at least one concrete expectation

skillspec grammar sensemake --view porting teaches the grammar progressively before import — use it to understand which constructs to promote from prose before running skillspec validate on a generated draft.

Get Started

Core Concepts

Guides

Spec Reference

SkillSpec v0 JSON Schema: Types and Validation Rules

Getting the Schema

Strict Validation

Type Overview

Safety Classes

Dependency Kinds

Import Roles

Resource Roles

Code Kinds

Artifact Kinds

Cross-Reference Rules

​Getting the Schema

​Strict Validation

​Type Overview

​Safety Classes

​Dependency Kinds

​Import Roles

​Resource Roles

​Code Kinds

​Artifact Kinds

​Cross-Reference Rules

Getting the Schema

Strict Validation

Type Overview

Safety Classes

Dependency Kinds

Import Roles

Resource Roles

Code Kinds

Artifact Kinds

Cross-Reference Rules