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.

skillspec compile compiles a skill.spec.yml file into harness guidance or a full Markdown rendering. For harness targets (codex-skill and claude-skill), the output is a thin loader SKILL.md that points agents to the colocated spec and runtime commands. The loader instructs agents to verify or install the skillspec CLI because the trampoline depends on it for route selection, phase control, progress recording, and alignment proof. For markdown, the output is a complete human-readable rendering of the SkillSpec behavioral contract.

​
Synopsis

skillspec compile <path> --target <codex-skill|claude-skill|markdown>

​
Options

FlagDescription
<path>Path to the skill.spec.yml file to compile.
--target codex-skill|claude-skill|markdownCompile target. See target descriptions below.
The compiled output is written to standard output.

​
Targets

​
codex-skill

Generates a SKILL.md loader for Codex and OpenAI Agents harnesses. The loader:
  • Identifies the skill.spec.yml relative to the loaded SKILL.md directory.
  • Directs the agent to start a guided run with skillspec run-loop ... --guide agent --json.
  • Tells the agent to use the JSON gate as internal control data — not to narrate it.
  • Instructs the agent to keep SkillSpec mechanics in the background.
  • Provides fallback installation instructions when the skillspec CLI is missing.
  • Falls back gracefully: if CLI installation is refused or impossible, directs the agent to read skill.spec.yml directly and manually follow the contract.

​
claude-skill

Generates a SKILL.md loader for Claude Code harnesses. Behavior and loader contract are identical to codex-skill but with Claude-specific frontmatter.

​
markdown

Generates a complete Markdown rendering of the full SkillSpec behavioral contract, including:
  • All routes, rules, elicitations, dependencies, imports, resources, code blocks, commands, recipes, states, closures, and tests.
  • Runtime contract and authoring contract sections.
  • SkillSpec CLI command reference for the compiled skill.

​
Examples

Compile to a Codex skill loader: 
skillspec compile ./skill.spec.yml --target codex-skill > SKILL.md
Compile to a Claude Code skill loader: 
skillspec compile ./skill.spec.yml --target claude-skill > SKILL.md
Compile to a full Markdown rendering for review: 
skillspec compile ./skill.spec.yml --target markdown > skill-full.md

​
Generated loader behavior

For codex-skill and claude-skill, the generated loader tells the agent:
  1. Use the directory containing the loaded SKILL.md as <skill_dir>.
  2. Start the guide: skillspec run-loop <skill_dir>/skill.spec.yml --input '<task>' --trace-dir "${PWD}/.skillspec/traces" --guide agent --json
  3. Resume an existing run: skillspec run-loop <skill_dir>/skill.spec.yml --resume <run_dir> --guide agent --json
  4. Keep SkillSpec mechanics in the background — no raw JSON narration to the user.
  5. Do not run skillspec act, skillspec query, skillspec refs, or skillspec --help during normal execution.
  6. For read-only diagnostic routes (e.g., doctor/source-shape assessment), run the diagnostic and stop — do not create progress ledgers unless the user asks for proof.
  7. If skillspec is not installed, ask the user to install it before continuing.
Always run skillspec grammar sensemake --view porting before compiling an imported spec so the harness understands the grammar version and spec constructs.
To compile all packages in a multi-skill workspace, use skillspec workspace compile instead. It rechecks convergence, blocks dependents whose dependencies did not compile, and writes a workspace-compile.report.md.
  • skillspec validate <path> — Validate the spec before compiling.
  • skillspec grammar sensemake --view porting — Load grammar context before compiling an imported spec.
  • skillspec workspace compile <manifest> — Compile all packages in a workspace manifest.
  • skillspec install skill <folder> — Install the compiled skill package into harness roots.

Build docs developers (and LLMs) love

Get started for freeTalk to us