Install Skill Pack

Install reviewed skills from the user's Git repository. The default path passes the bare source to the CLI and follows the remote's default branch. Branch and commit pins are optional.

Install globally by default; run a project-local install only when the user explicitly requests one. Select the target agents in this order: the agents the user names for this install; otherwise a default agent list the user has recorded in their instruction files; otherwise the harnesses the CLI detects on this host, confirmed once with the user before installing. Pass each target as an explicit --agent. Never use the broad --all option or omit --agent: without it the CLI picks targets itself and, when it detects no harness, installs to every agent it knows. Let the CLI manage the canonical global package and agent-facing links.

Review the source directly. Third-party scans are optional; a missing scanner result is neither a pass nor a blocker.

Quick Path

1. Check prerequisites: Node with npm and npx at the version the resolved Skills CLI release declares (releases 1.5.23 through 1.7.1 require Node 22.20.0 or later), git, python3 for the rename script, and network access to the repository host and the npm registry. If a tool is missing or too old, stop and report it rather than installing it.

   Resolve the repository source and selected skill names. Accept GitHub shorthand, a full repository URL, or another cloneable Git URL. Read references/skills-cli-usage.md for target selection and detection, the current CLI contract, symlink mode, and per-agent verification. Resolve names from the current request and already-established session scope, including a skill just published for installation. If that leaves the selection unclear, list the repository's skills first; install every package only when the user explicitly requested the complete pack.

2. Select one revision mode:

   • Default: no revision input. Use the remote default branch at its latest commit and keep the CLI source bare, for example owner/repo.
   • Branch: append #<branch> to the CLI source.
   • Commit: require an exact full commit ID and use the detached-checkout path below. Do not append a raw commit ID to the CLI source.

   Branch and commit inputs are mutually exclusive. Preserve the user's source form for the CLI. Normalize it separately for Git review; for example, clone owner/repo through https://github.com/owner/repo.git. Read and apply references/revision-selection.md to prepare install_source, reviewed_sha, and the review checkout.

3. Resolve npm's current stable skills@latest version once per operation and verify its version and live interface through the CLI-usage reference. Then resolve the target agents as that reference describes; a detected list needs the user's one confirmation before step 8. Stop if the version is malformed, the reported version differs, or a selected target ID is unsupported. An npm policy such as min-release-age may refuse a young release with an error that reads like a missing version; step down to the newest release the policy allows instead of bypassing the policy. Executing the npm CLI is a separate package-manager trust boundary; reviewing a skill repository does not establish the CLI publisher's integrity.
4. Prepare the disposable checkout through the selected revision path. Record the checked-out commit as reviewed_sha. Stop if the source cannot be mapped to one repository, the branch is absent, the commit is unreachable, or the exact requested commit differs from the checkout.
5. Locate every requested skill by its frontmatter name and require exactly one matching package per name. Before installing anything, read its complete SKILL.md and every file in its package, including references, scripts, assets, templates, configuration, symlinks, and otherwise non-obvious files. For a full-pack install, review every package that will be installed; do not sample.

6. Read and apply references/source-review.md. Record concise observable evidence for each selected skill: files inspected, intended capability, commands and external access, material findings, and a pass or block decision.

   Then resolve names. Compare the selected names with installed global skills from other sources and with the target harnesses' built-in commands. When the renames file ~/.agents/skill-pack-renames.json has an entry for this source, or a collision needs one, read and apply references/renames.md: the user decides which side takes a prefix, and scripts/rename_skills.py writes the renamed and rewritten packages. Review that output as part of this step.

7. Immediately before a default-branch or named-branch installation, use the revision reference to confirm the remote still points to reviewed_sha. If it changed, discard the checkout and repeat the review against the new snapshot. An exact commit is immutable once the checkout and full ID match.

8. Install with the resolved CLI version, passing every selected target agent and skill explicitly, one --agent per target:

   npx --yes "skills@$skills_cli_version" add \
     "$install_source" \
     --global \
     --agent <agent-id> \
     --agent <agent-id> \
     --skill <skill-name> \
     --yes

   Default mode leaves install_source bare, so the CLI follows the remote's default branch without assuming main or master. Commit mode uses the reviewed local checkout because remote #ref does not reliably accept a raw commit ID. Omit --copy: the verified normal path uses the CLI's default canonical-copy plus agent-symlink mode. Targets that all share one skills directory get copy mode anyway; the CLI-usage reference says how to verify that case.

   When step 6 wrote renamed packages, run the same command twice: once with install_source for the packages the script listed as unchanged, and once with the script's output directory as the source for the packages it listed as written, by their new names.

9. Inspect skills list --global --agent <id> --json for every selected target, using the installed names. Require each name and canonical path; for a detected harness, also require its display name in agents. An absent universal harness can be canonical-ready without appearing there, so verify it from the install summary and report runtime discovery as unavailable rather than creating its config directory. Compare canonical files and non-universal links per the CLI-usage reference. Content, link, or detected-harness discovery failures leave the install unverified.
10. Remove the disposable checkout and any renamed output only after content and discovery verification pass. Then complete the rename record and any old-name removal as the renames reference describes.

If installation returns an uncertain result, inspect canonical content and agent-facing links before rerunning it. Preserve the reviewed revision and selection while diagnosing; an unavailable universal harness does not justify another install or a new configuration directory.

Selecting Skills

A repository can group packages into directories that stand for an install set, such as skills/minimal/ for the default install. When the user asks for a set, list the package names under that directory in the reviewed checkout and pass each as --skill; keep install_source as the repository source so the tracked metadata points at the remote. A set only decides availability; each skill's own description and invocation settings still decide when it runs.

Add one --skill <frontmatter-name> argument per requested package to the install command. Use --skill '*' only for an explicitly requested complete pack, after reviewing every package. If a name is absent, stop; do not silently switch revisions, repositories, or local checkouts.

Revisions And Updates

• Bare sources and named branches follow their remote and require review again after a commit change. Exact commits reinstall through the detached checkout; the CLI cannot update that temporary local source from the remote.
• Renamed packages also install from a temporary local source, so skills update skips them as a local path. Refresh a source that has a renames entry by running this skill on that source again; the entry reapplies the prefix and rewrites invocations that upstream added since.

Only an explicit request to update every tracked global skill authorizes:

npx --yes "skills@$skills_cli_version" update --global --yes

It can fetch unreviewed sources outside the current repository. State that scope beforehand. For named skills, put their names before --global.

Gotchas

• Running the Skills CLI trusts its npm publisher and executes remote CLI code. The source review covers selected skill packages, not npm provenance or the CLI implementation.
• #<branch> selects a branch. Do not use @<branch>; the CLI interprets @ as a skill filter.
• Do not pass CLI flags through a shell variable. Zsh does not word-split an unquoted variable, so a flags string arrives as one argument; the CLI ignored it, installed project-locally, and still printed Installed. Write flags literally and confirm the mode with the per-agent listing before reporting success.
• An installed canonical package may have been edited in place by another session or harness since its install. Before an install that overwrites one, compare the canonical package against the reviewed revision; surface material diffs to the user instead of silently discarding them, and re-review anything the overwrite would carry away.
• Installation can overwrite selected skills. Back up only those directories when the exact old version must be preserved until verification passes.
• Global installation does not authorize deletion of unrelated or stale skills. Remove those only when the user explicitly names them.

Validation

Maintainer note for the repository that ships this skill, not part of an installation: before publishing a change to this skill, validate the package and confirm repository discovery. Run the active skill-builder validator against skills/minimal/install-skill-pack, then run:

npx --yes "skills@$skills_cli_version" add . --list --full-depth

Output

Report the resolved Skills CLI version, repository source, revision mode, reviewed commit, selected agents and skills, source-review decision, canonical content comparison, link topology, and each selected harness's discovery or canonical-ready status. Name the rule that selected the target agents: named by the user, a recorded default list, or detected and confirmed. For a source with renames, list each old and new name, the packages installed from the renamed output, and the mentions the script left for review. For an exact commit, also state that automatic remote updates are unavailable and the pinned workflow must be rerun. If blocked, identify the observable finding, affected file or command, and whether the risk is inherent to the requested capability or unexplained.