SkillSpec Imports: Runtime-Loadable Instruction Files

Imports are v0’s runtime-loadable instruction layer. They exist for Markdown or text that the harness should deliberately read while executing a skill: shared operating policy, branch-specific references, procedure documents, examples, or another skill document. Importing Markdown is not inheritance — it never merges another spec into the current document, never creates routes, rules, commands, or tests implicitly, and never weakens forbids. The current skill.spec.yml remains the only grammar tree.

Import Fields

import  = "path" ":" string ,
          "role" ":" import-role ,
          [ "description" ":" string ] ,
          [ "section" ":" string ] ,
          [ "load" ":" import-load ] ,
          [ "requires" ":" import-requires ] ,
          [ "used_by" ":" sequence-of import-use ] ,
          [ "load_when" ":" sequence-of string ] ;

Field	Required	Notes
`path`	✅	Relative path from the `skill.spec.yml` directory to the Markdown file.
`role`	✅	Declares how the harness should treat the content.
`description`	—	Human description of what this import provides.
`section`	—	Narrows the import to a single named heading and its children.
`load`	—	`always` or `on_demand` (default). Controls when the harness reads the file.
`requires.imports`	—	List of import ids that must be loaded before this one.
`used_by`	—	Declares which skill constructs depend on this import. Required for on-demand imports that are not referenced by code or recipe.
`load_when`	—	Advisory list of conditions under which to load. Harness-specific.

Import Roles

Choosing the right role tells the harness — and future readers — how to treat the imported content.

policy — shared operating rules

Rules that apply before any task action. Always load at startup. Use for plugin-level or team-wide policies that every skill in a package must obey.

imports:
  shared_operating_rules:
    path: ../INDEX.md
    role: policy
    section: Shared operating rules
    load: always
    description: Shared rules every onboard skill must obey.

reference — branch-specific material

Reference documents loaded only when a particular route, rule, or recipe is active. Connect via used_by or requires.imports.

imports:
  task_routing:
    path: references/task-routing.md
    role: reference
    used_by:
      - kind: route
        id: local_cli

procedure — step-by-step guidance

Procedure documents describe how to execute a task path. Connect them to a recipe that uses load_import steps, or via used_by.

imports:
  flow_authoring:
    path: references/flow-authoring.md
    role: procedure
    used_by:
      - kind: route
        id: author_flow

example — worked examples

Worked examples of correct behavior. On-demand only; connect to a code block or recipe that references them.

skill — another skill document

A full skill document loaded as active guidance. Useful for skills that hand off to or compose with another skill’s prose without merging its spec structure.

Load Modes

Mode	Behavior
`always`	Loaded after the spec is loaded and before any task actions begin. Can stand alone without a `used_by` reference. Use only for small, load-bearing policy that must be in context before the agent acts.
`on_demand` (default)	Loaded only when its connected route, rule, recipe, code path, or parent import is active. Must be connected to the runtime graph by `used_by`, `requires.imports`, `Code.requires.imports`, `Recipe.requires.imports`, or a `load_import` recipe step.

Use always sparingly. Every always import adds to the agent’s context window before a single task action runs. Reserve it for authoritative policy documents, not convenience references.

Sections

section narrows an import to a single named heading and its child content until the next heading at the same or higher level.

imports:
  shared_rules:
    path: ../INDEX.md
    role: policy
    section: Shared operating rules
    load: always

When section is absent, the whole file is the import body.

If section is declared but the heading cannot be found in the file, the harness must fail closed with a clear missing-import error. It must not silently load the whole file or fall back to a nearby heading. Ambiguous section resolution is harder to debug than a clear validation error.

Nested Imports

requires.imports is the only v0 nesting mechanism. It forms a directed acyclic graph of import ids. All imports live in the main spec’s top-level imports map; nesting is declared as references between those ids, not as declarations inside imported Markdown. When a harness loads an import:

Resolve the import id in the current spec’s imports map.
Load every id in requires.imports first, in listed order (topological).
Then load the requested import.
Skip duplicate loads during one decision run.

imports:
  a:
    path: a.md
    role: procedure
    requires:
      imports: [b]
  b:
    path: references/b.md
    role: reference
    requires:
      imports: [c]
  c:
    path: ../shared/c.md
    role: policy
    used_by:
      - kind: recipe
        id: use_a

All three paths (a.md, references/b.md, ../shared/c.md) resolve relative to the directory containing skill.spec.yml, even when b is loaded because a requires it. Cycles are invalid. The following will fail skillspec validate:

imports:
  a:
    path: a.md
    role: reference
    requires:
      imports: [b]
  b:
    path: b.md
    role: reference
    requires:
      imports: [a]   # ❌ cycle: a → b → a

Path Resolution

Import paths resolve relative to the directory containing skill.spec.yml. That rule applies to all imports, including nested ones.

skill/
  skill.spec.yml    ← resolution root for all imports
  SKILL.md
  references/task-routing.md
plugin/
  INDEX.md

From skill/skill.spec.yml:

imports:
  shared_rules:
    path: ../plugin/INDEX.md   # resolves to plugin/INDEX.md
    role: policy
    load: always
  task_routing:
    path: references/task-routing.md   # resolves to skill/references/task-routing.md
    role: reference

Do not use:

~ home directory expansion
Environment variable substitution ($VAR, ${VAR})
Shell command substitution
Markdown links as import paths
Absolute paths (harness-specific behavior only)
URLs (harness-specific behavior only)

Relative paths using ../ are allowed so a skill can import plugin-level shared guidance. Harnesses may still apply package-root or sandbox policy before reading the file.

Validating Imports

skillspec imports check ./skill.spec.yml

This command validates:

Declared import paths resolve to existing files
Declared sections exist in those files
Explicit nesting is consistent (no cycles, all ids exist)
Dependency-first load order is satisfiable

It does not inject imported content into an agent context. Runtime loading remains the harness’s responsibility.

Example: Import Graph

The following is the conformance fixture for imports, from conformance/valid/imports.skill.spec.yml:

schema: skillspec/v0
id: conformance.imports
title: Imports Fixture
description: Valid import graph fixture.

routes:
  - id: local
    label: Local

imports:
  shared_policy:
    path: ../../README.md
    role: policy
    load: always
  task_reference:
    path: ../../spec/imports.md
    role: reference
    used_by:
      - kind: route
        id: local

recipes:
  task:
    steps:
      - load_import: task_reference

tests:
  - name: route assertion
    input: local task
    expect:
      route: local

shared_policy uses load: always — it is loaded at startup with no used_by required. task_reference is on_demand and declares used_by pointing at the local route, satisfying the reference closure requirement.

Resources vs. Imports

The decision between imports and resources determines whether a file becomes active guidance or preserved provenance.

Aspect	Imports	Resources
Purpose	Runtime guidance loaded into agent context	Provenance, source evidence, scripts, assets
When loaded	Deliberately by harness during a run	Not loaded as guidance; referenced for provenance
Grammar role	Active instruction material	Supporting material and source evidence
Code provenance	`provenance.import` for code extracted from runtime guidance	`provenance.resource` for code extracted from source material
Use when	Agent must read the file as active task guidance	File is source provenance, an asset, a script, or evidence
Validated by	`skillspec imports check`	`skillspec validate` cross-reference checks

A source file, fixture, evidence document, or script that supports code provenance but should not appear in the agent’s context window belongs in resources. A shared policy document, procedure guide, or branch-specific reference that the agent must read during a run belongs in imports.

Get Started

Core Concepts

Guides

Spec Reference

SkillSpec Imports: Runtime-Loadable Instruction Files

Import Fields

Import Roles

Load Modes

Sections

Nested Imports

Path Resolution

Validating Imports

Example: Import Graph

Resources vs. Imports

​Import Fields

​Import Roles

​Load Modes

​Sections

​Nested Imports

​Path Resolution

​Validating Imports

​Example: Import Graph

​Resources vs. Imports

Import Fields

Import Roles

Load Modes

Sections

Nested Imports

Path Resolution

Validating Imports

Example: Import Graph

Resources vs. Imports