01Start · Overview

A suitcase for agent skills.

Skill Suitcase is an agent-first skill package manager backed by a Git catalog. One JSON-first CLI inspects, installs, updates, and recovers skills across agent runtimes without ever treating live agent homes as the source of truth.

First command

# install the CLI (Node.js 20 or newer)
npm install --global skill-suitcase

# point at a catalog: skill-suitcase.yaml + skills/<name>/
SRC="/path/to/skills-catalog"

# audit it read-only (writes nothing)
skill-suitcase import --source "$SRC" --json
skill-suitcase validate --source "$SRC" --json
skill-suitcase status --source "$SRC" --json

That is the safe starting path. Read-only commands never create install roots, runtime homes, receipts, symlinks, or catalog files. Inspect their JSON before staging or mutating anything.

Follow the getting-started walkthrough for a disposable first install and receipt-backed rollback. Use validate --strict as the release gate for a reviewed catalog, not as a requirement for its minimal starter skill.

The workflow

The catalog is canonical; runtimes are targets. Every install follows the same rhythm: inspect current state, stage reviewed content, apply through an explicit approval boundary, and recover with receipts when state drifts.

1 Inspect skill-suitcase status --source "$SRC" --target codex --jsonRead-only commands classify catalog-planned installs as current, missing, version, behind, dirty, blocked, or unknown without touching the target. 2 Stage skill-suitcase pack --source "$SRC" --target codex --output "$OUT" --jsonPack an immutable bundle into an explicit output directory, or build a deterministic plan lock, and review it like any other change. 3 Apply skill-suitcase apply --source "$SRC" --target codex --artifact "$ARTIFACT" --jsonTransactional install from exactly one plan lock or staged artifact. The target receipt gets a record for every managed skill, including ownership and rollback state. 4 Recover skill-suitcase repair --source "$SRC" --target codex --skill <name> --dry-run --jsonReceipt-aware recovery: track, reconcile, repair, prune, promote, import-target, and rollback, each with its own explicit boundary. 5 Refresh skill-suitcase upstream check --source "$SRC" --jsonPinned upstream sources refresh the catalog only, through isolated fetch, diff, and Git review. Never a direct target installer.

Safety model

The same rules apply to agents and humans alike. Drift is a report, never permission.

Read-only import, validate, targets, plan, status, diff, every --dry-run mode, upstream check, and upstream fetch --dry-run never write roots, receipts, symlinks, or catalog files.
Approval apply requires exactly one approved input: a plan lock or a staged artifact. Neither binds the resolved install root, path overrides, or copy-versus-symlink mode, so approve those at invocation time.
Approval reconcile, repair, prune, promote, and import-target mutations require --apply plus an explicitly named scope. prune --apply additionally requires the exact plan ID returned by its dry-run.
Approval track mutates on explicit invocation, writes only a receipt and never skill files, and requires the target to exactly match catalog source. Its --skill selection is optional; omitting it uses all-planned-skills mode.
Approval rollback requires an explicit receipt path.
Refused Provider-backed targets (OpenCode and Pi) are read-only. Target-aware materialization and mutation return read_only_target instead of writing provider-managed homes.
Refused Nothing auto-commits. upstream import --apply writes only catalog source and the upstream lock, never live agent homes, and leaves the Git diff for review.

The full model, including receipts and the status enum, is on the safety model page.

Modeled targets

Target IDs are openclaw, codex, openclaw-codex, agents, claude, hermes, opencode, pi, and grok. Paths stay portable with explicit overrides:

--agents-skills <dir>shared agents skill root

--codex-home <dir>Codex home directory

--codex-skills <dir>Codex skills root

--claude-skills <dir>Claude skills root

--hermes-skills <dir>flat Hermes root, or the owned external-root path for categorized Hermes

--grok-skills <dir>Grok skills root

Categorized Hermes targets install at <external-root>/<category>/<skill> with one receipt at the owned root. The root must already exist, be registered in Hermes skills.external_dirs, and pass overlap, precedence, identity-shadow, and symlink checks before live target work.

Where next

Install: get the CLI, the operator skill, and a catalog onto a machine.
Safety model: the inspect, stage, mutate phases, receipts, and the status enum.
Catalog model: the manifest contract, variants, groups, and source policy.
Upstream refresh: the catalog-only lane for pinned upstream sources.
Agent workflows: the audit loop, recovery decision tree, and approval-gated operational recipes.
Troubleshooting: refusal codes and what each status state asks you to do.
CLI reference: every command on one page.