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:
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
port-one-shot, the compiled output lands at ./draft/.skillspec/port/compiled.codex-skill.md.
To compile for Claude Code:
Detect Harness Roots
Before installing, check which harness roots SkillSpec can see on the current machine:~/.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 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:
--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:
--retire-existing does three things in order:
- Backs up the old skill folder to
~/.skillspec/backups/retired-skills/retire-<timestamp>-<pid>/<target>/<skill-name>/(or underSKILLSPEC_HOMEwhen that environment variable is set). - Removes the old skill from harness discovery by deleting the original install directory.
- Installs the reviewed replacement at the same name.
--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.
- Install with retirement
- Install to all detected roots
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 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
--roots scopes the scan to specific directories:
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.