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.

Once your skill.spec.yml passes validation, imports check, deps check, and scenario tests, the last two steps before handing the skill to an agent are compilation and install. Compilation generates a thin SKILL.md loader that tells the harness where the spec lives and instructs the agent to use SkillSpec CLI commands for route, phase, progress, and alignment proof — keeping the active prompt small. Install copies that generated package into one or more detected harness skill roots so the agent can discover and invoke it.

​
Compile Targets

skillspec compile supports three output targets:
TargetDescription
codex-skillGenerates a Codex / OpenAI Agents loader. The loader tells the agent to locate the colocated skill.spec.yml and start skillspec run-loop with the user’s task.
claude-skillGenerates a Claude Code loader with the same contract, adapted for the Claude harness.
markdownGenerates a complete Markdown rendering of the full behavioral contract — routes, rules, dependencies, commands, tests, and proof requirements — for review or documentation purposes.
For agent-facing installs, use codex-skill or claude-skill. The generated loaders are intentionally minimal: they point the agent at the spec rather than duplicating its content, so the contract can evolve without regenerating a large SKILL.md on every edit.

​
Compile Command

skillspec compile ./skill.spec.yml --target codex-skill
The compiled loader is written next to the spec by default. If you are using port-one-shot, the compiled output lands at ./draft/.skillspec/port/compiled.codex-skill.md. To compile for Claude Code: 
skillspec compile ./skill.spec.yml --target claude-skill
To generate a full Markdown rendering for review: 
skillspec compile ./skill.spec.yml --target markdown > skill-full.md

​
Detect Harness Roots

Before installing, check which harness roots SkillSpec can see on the current machine: 
skillspec install targets
This reports detected roots for Agents (~/.agents/skills), Codex (~/.codex/skills), and Claude repo-local (<repo>/.claude/skills), along with whether each root was actually detected on disk. Use this output to choose your --target flags.

​
Install a Skill

skillspec install skill ./my-skill-spec \
  --target agents \
  --target codex \
  --dry-run
skillspec install skill copies the generated skill folder — SKILL.md, skill.spec.yml, and all declared package-local files from imports, resources, code sources, and file dependencies — into each selected harness root. The skill name is inferred from the folder name by default; use --name <name> to override. Always run with --dry-run first to see the planned writes before anything is written to disk.

​
Dry Run First

--dry-run shows every planned install path and file without writing anything. It is the safest way to confirm targets and names before committing: 
skillspec install skill ./my-skill-spec \
  --target agents \
  --target codex \
  --dry-run
The output lists each target root, whether an existing skill was found at that path, whether it would be retired, and the intended install directory. When you are satisfied with the plan, remove --dry-run to perform the actual install.

​
Retiring an Existing Skill

When you are replacing an active prose skill with a SkillSpec-backed version, use --retire-existing: 
skillspec install skill ./my-skill-spec \
  --target agents \
  --target codex \
  --retire-existing
--retire-existing does three things in order:
  1. Backs up the old skill folder to ~/.skillspec/backups/retired-skills/retire-<timestamp>-<pid>/<target>/<skill-name>/ (or under SKILLSPEC_HOME when that environment variable is set).
  2. Removes the old skill from harness discovery by deleting the original install directory.
  3. Installs the reviewed replacement at the same name.
This preserves the original prose skill as a recoverable backup without leaving it active in the harness alongside the new contract. The backup is a plain directory copy — no special format required to restore it. --force and --retire-existing are mutually exclusive. Use --retire-existing when you want a clean replacement with a backup; use --force only when overwriting an existing directory without a backup is intentional. 
# Dry run first
skillspec install skill ./my-skill-spec \
  --target codex \
  --retire-existing \
  --dry-run

# Actual install once the plan looks right
skillspec install skill ./my-skill-spec \
  --target codex \
  --retire-existing

​
Post-Install Verification

After a successful install, restart the harness so it picks up the new skill directory. Then check that SkillSpec sees the installed skill correctly: 
skillspec status
skillspec status is a read-only inventory command. It reports:
  • Router and durable-executor installed/enabled/disabled state
  • Supported and scanned roots
  • Router index existence, staleness, and last-updated time
  • SkillSpec-backed versus legacy prose skills by name, path, and visibility
If you are running without the router, --roots scopes the scan to specific directories: 
skillspec status --roots ~/.codex/skills
Once the harness is restarted and the skill appears in skillspec status, open a new agent session and interact with the installed skill normally. The compiled loader will tell the agent to find skill.spec.yml and start skillspec run-loop with your task.
For multi-skill repositories where several SKILL.md packages live under a shared root, the workspace install flow handles package discovery, dependency ordering, visibility controls, and harness-path preservation automatically. See the workspace skills guide for the skillspec workspace map, workspace import, workspace compile, and workspace install commands.

Build docs developers (and LLMs) love

Get started for freeTalk to us