skillspec install — Install Skills into Agent Harnesses

skillspec install installs a generated skill folder containing SKILL.md, skill.spec.yml, and declared package-local files into one or more detected harness roots. This command is for already-reviewed, generated packages. In the harness, install skill <raw-source-or-uri> is an end-state intent: assess, import/promote, validate, compile, dry-run, approve targets/retirement, then install.

Synopsis

skillspec install targets
skillspec install skill <folder> \
  [--target <agents|codex|claude-local>] \
  [--all-detected] \
  [--dry-run] \
  [--name <name>] \
  [--force] \
  [--retire-existing]

`install targets`

Lists detected harness skill roots. No arguments required.

skillspec install targets

Output is always JSON. Reports detected agents (~/.agents/skills), codex (~/.codex/skills), and claude-local (.claude/skills in the nearest ancestor .claude directory from the current working directory).

`install skill` options

Flag	Description
`<folder>`	Path to the compiled skill folder containing `SKILL.md` and `skill.spec.yml`.
`--target agents\|codex\|claude-local`	Target harness root. Repeatable to install to multiple targets.
`--all-detected`	Install to all detected harness roots. Mutually exclusive with specific `--target` values when used to override.
`--dry-run`	Plan the install without writing any files. Always run this first.
`--name <name>`	Override the skill name (default: inferred from the folder name). Must be lowercase letters, digits, `-`, `_`, or `.`.
`--force`	Overwrite an existing skill folder without prompting. Mutually exclusive with `--retire-existing`.
`--retire-existing`	Back up the existing skill to `~/.skillspec/backups/retired-skills`, remove it from harness discovery, then install the replacement. Mutually exclusive with `--force`.

--force and --retire-existing are mutually exclusive. Use --retire-existing when replacing an active prose skill to preserve the backup and ensure clean harness discovery. Use --force only to overwrite a non-active or test install.

What a skill package contains

install skill copies all declared package-local files from the spec alongside SKILL.md and skill.spec.yml:

All imports: paths declared in the spec.
All resources: paths declared in the spec.
File-sourced code: blocks.
File dependencies: with local paths.
Source evidence files recorded in spec metadata.

Paths must stay within the skill folder. Absolute paths, URLs, and ../ traversals are rejected.

`--retire-existing` behavior

When replacing an active prose skill with a SkillSpec-backed version:

The existing skill folder is backed up under ~/.skillspec/backups/retired-skills/retire-<timestamp>-<pid>/<target-id>/<skill-name>/ (or $SKILLSPEC_HOME/backups/retired-skills/...).
The old folder is removed from the harness discovery root.
The new compiled package is installed at the same skill name.

The backup directory is timestamped and process-scoped so multiple retirements do not collide. The backup is not automatically deleted; keep it until you have verified the new skill works correctly.

Examples

Dry-run before any actual install:

skillspec install skill ./examples/pdf \
  --target agents \
  --target codex \
  --dry-run

Install to Codex only:

skillspec install skill ./examples/pdf \
  --target codex

Replace an existing prose skill with a SkillSpec-backed version:

skillspec install skill ./examples/pdf \
  --target agents \
  --target codex \
  --retire-existing \
  --dry-run

# After reviewing the dry-run output:
skillspec install skill ./examples/pdf \
  --target agents \
  --target codex \
  --retire-existing

Install to all detected harness roots:

skillspec install skill ./examples/pdf --all-detected --dry-run

After install

Restart the harness — Agents, Codex, and Claude Code load skills at startup. A restart is required for the new skill to be discoverable.
Run skillspec status — Verify that the installed skill appears with the expected path and visibility.
Interact with the skill — Test the installed SkillSpec-backed skill through the agent before opening any PR or closing the porting task.

`skillspec status`

skillspec status [--roots <path>...] [--json]

Read-only installation inventory. Reports:

Router and durable-executor installed/enabled/disabled state.
Supported and scanned roots.
Router index exists/stale/updated-at data.
Managed router guard hook state.
SkillSpec-backed versus legacy prose skills by name, path, and visibility.

Without --roots, scans router config roots when available, otherwise scans detected harness roots.

# Show status for all detected roots
skillspec status

# Show status for specific roots as JSON
skillspec status --roots ~/.agents/skills ~/.codex/skills --json

skillspec compile <path> --target <target> — Compile the spec before installing.
skillspec workspace install <manifest> — Install an entire workspace build.
skillspec router index refresh — Refresh the router index after installing new skills.
skillspec status — Verify installed skills and router state.

Runtime Commands

Authoring Commands

Installation & Discovery

skillspec install — Install Skills into Agent Harnesses

Synopsis

`install targets`

`install skill` options

What a skill package contains

`--retire-existing` behavior

Examples

After install

`skillspec status`

​Synopsis

​install targets

​install skill options

​What a skill package contains

​--retire-existing behavior

​Examples

​After install

​skillspec status

​Related commands

Synopsis

`install targets`

`install skill` options

What a skill package contains

`--retire-existing` behavior

Examples

After install

`skillspec status`

Related commands