Install the CLI, the skill, and a catalog.

Install the CLI

Skill Suitcase requires Node.js 20 or newer.

npm install --global skill-suitcase

To run from source instead, use npm's ephemeral executor so the pinned pnpm version runs without changing Corepack or global package-manager shims:

if mkdir -p "$HOME/repos" &&
  {
    if test -e "$HOME/repos/skill-suitcase/.git"; then
      git -C "$HOME/repos/skill-suitcase" pull --ff-only
    else
      git clone https://github.com/calvinnwq/skill-suitcase.git "$HOME/repos/skill-suitcase"
    fi
  } &&
  cd "$HOME/repos/skill-suitcase"
then
  pnpm() {
    npm exec --yes --package=pnpm@10.34.4 -- pnpm "$@"
  }
  test "$(pnpm --version)" = "10.34.4" &&
  pnpm install --frozen-lockfile &&
  pnpm run build
else
  printf 'Source checkout setup failed.\n' >&2
  false
fi

Then invoke the source build directly:

export CLI="$HOME/repos/skill-suitcase/dist/src/cli.js"
node "$CLI" targets --source "$HOME/.skill-suitcase/skills" --json

Install the operator skill

The package ships an operator skill that teaches an agent the read-only-first workflow. Copy the whole skills/skill-suitcase directory, not just SKILL.md.

Choose the skill root for the agent runtime you are configuring. Edit the one active assignment below when you are not installing for Codex.

# use the source checkout when present, otherwise the global npm install
if test -d "$HOME/repos/skill-suitcase/skills/skill-suitcase"; then
  SKILL_SRC="$HOME/repos/skill-suitcase/skills/skill-suitcase"
else
  SKILL_SRC="$(npm root -g)/skill-suitcase/skills/skill-suitcase"
fi

# choose one runtime root: Codex $HOME/.codex/skills, Claude $HOME/.claude/skills, shared agents root $HOME/.agents/skills, or Grok Build $HOME/.grok/skills
# Hermes roots: default profile $HOME/.hermes/skills or named profile $HOME/.hermes/profiles/<name>/skills
AGENT_SKILLS_DIR="$HOME/.codex/skills"

# install into the selected root
install_operator_skill() (
  if ! test -d "$SKILL_SRC"; then
    printf 'Skill source not found: %s\n' "$SKILL_SRC" >&2
    return 1
  fi

  mkdir -p "$AGENT_SKILLS_DIR" || return 1
  INSTALL_TMP="$(mktemp -d "$AGENT_SKILLS_DIR/.skill-suitcase.install.XXXXXX")" || return 1
  mkdir "$INSTALL_TMP/replacement" || {
    rm -rf "$INSTALL_TMP"
    return 1
  }
  if ! cp -R "$SKILL_SRC/." "$INSTALL_TMP/replacement/"; then
    rm -rf "$INSTALL_TMP"
    return 1
  fi

  TARGET="$AGENT_SKILLS_DIR/skill-suitcase"
  HAD_TARGET=false
  if test -e "$TARGET" || test -L "$TARGET"; then
    mv "$TARGET" "$INSTALL_TMP/previous" || {
      rm -rf "$INSTALL_TMP"
      return 1
    }
    HAD_TARGET=true
  fi

  if mv "$INSTALL_TMP/replacement" "$TARGET"; then
    rm -rf "$INSTALL_TMP"
  else
    if "$HAD_TARGET" && ! mv "$INSTALL_TMP/previous" "$TARGET"; then
      printf 'Replacement failed; previous skill preserved at: %s\n' "$INSTALL_TMP/previous" >&2
      return 1
    fi
    rm -rf "$INSTALL_TMP"
    return 1
  fi
)

install_operator_skill

Restart the agent runtime after installing or replacing a skill.

Install or refresh the catalog

A catalog is any directory with skill-suitcase.yaml and skills/<name>/SKILL.md. Git backing is the preferred operating model.

Inspect an existing checkout before deciding whether it needs an update. Cloning or pulling mutates the catalog and requires explicit approval naming the catalog path and action.

unset SRC
CATALOG_DIR="$HOME/.skill-suitcase/skills"
if test -e "$HOME/.skill-suitcase/skills/.git" &&
  git -C "$CATALOG_DIR" status --short --branch
then
  export SRC="$CATALOG_DIR"
else
  printf 'Catalog checkout is missing; SRC was not exported.\n' >&2
  false
fi

Follow the authoritative approval-gated catalog checkout runbook in INSTALL.md for an approved clone or update.

After explicit approval naming the remote and destination, continue with the approved clone. Replace <your-catalog-remote> with the approved HTTPS remote URL, then run:

unset SRC
CATALOG_DIR="$HOME/.skill-suitcase/skills"
CATALOG_REMOTE="<your-catalog-remote>"
if mkdir -p "$HOME/.skill-suitcase" &&
  git clone "$CATALOG_REMOTE" "$CATALOG_DIR"
then
  export SRC="$CATALOG_DIR"
else
  printf 'Catalog checkout update failed; SRC was not exported.\n' >&2
  false
fi

If you do not have a catalog yet, the getting-started walkthrough creates a guarded minimal catalog without overwriting any existing catalog path.

Verify with a read-only audit

skill-suitcase import --source "$SRC" --json
skill-suitcase validate --source "$SRC" --json
# reviewed-catalog release gate
skill-suitcase validate --source "$SRC" --strict --json
skill-suitcase targets --source "$SRC" --json
skill-suitcase status --source "$SRC" --json

Use non-strict validation for the minimal starter catalog. Strict validation additionally applies the production Skillify authoring contract and is the release gate for a reviewed catalog.

The full agent setup runbook, including per-runtime pack and apply examples, lives in INSTALL.md. Continue with agent workflows for the audit loop and state-specific operational recipes.