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 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

FlagDescription
<folder>Path to the compiled skill folder containing SKILL.md and skill.spec.yml.
--target agents|codex|claude-localTarget harness root. Repeatable to install to multiple targets.
--all-detectedInstall to all detected harness roots. Mutually exclusive with specific --target values when used to override.
--dry-runPlan 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 ..
--forceOverwrite an existing skill folder without prompting. Mutually exclusive with --retire-existing.
--retire-existingBack 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:
  1. 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/...).
  2. The old folder is removed from the harness discovery root.
  3. 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

  1. Restart the harness — Agents, Codex, and Claude Code load skills at startup. A restart is required for the new skill to be discoverable.
  2. Run skillspec status — Verify that the installed skill appears with the expected path and visibility.
  3. 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us