[Feature]: `npx skills install` — restore all skills from skills-lock.json (npm ci equivalent)

[Yuzu02]

Problem

Currently, skills-lock.json exists to track installed skills and their sources, but there is
no command to restore skills from it. Running npx skills update when no skills are installed
does nothing — it silently exits because the command scans for already-installed skills first
and then consults the lock file. This makes the lock file useless for reproducible onboarding
in teams and CI environments.

The expected workflow for a shared project in a team is:

1. Developer A installs skills → skills-lock.json is generated and committed to the repo
2. Developer B clones the repo → runs one command to restore all skills
3. Step 2 is currently impossible without manually scripting npx skills add <owner/repo>
   for every single skill

This forces teams to either commit the skill files directly (noisy, skills are dependencies
not source) or maintain a parallel install script that duplicates what the lock file already
knows — defeating the purpose of having a lock file at all.

Proposed Solution

Add a npx skills install command (with npx skills ci as a strict alias, mirroring
npm install vs npm ci) that:

• Reads skills-lock.json from the project root (or ~/.agents/.skill-lock.json for global)
• Installs every skill entry in the lock file to its respective agent paths
• Respects the scope (project vs global) as stored in the lock file
• Is idempotent — skips skills that are already installed and up-to-date (unless --force)
• Returns a non-zero exit code on failure, making it reliable for CI pipelines

The lock file already contains all information needed per entry: sourceUrl, skillFolder,
and skillFolderHash. The install command would simply traverse those entries and invoke
the existing install logic.

Proposed CLI interface:
npx skills install # install from project-level skills-lock.json
npx skills install -g # install from global ~/.agents/.skill-lock.json
npx skills install --force # reinstall even if already present
npx skills ci # strict mode: fail if lock file is missing or incomplete

Alternatives Considered

1. Manually scripting npx skills add per skill (e.g. in a Makefile or mise task):
   Works, but requires maintaining a separate script that duplicates what the lock file
   already tracks. Every time a skill is added or removed, both the lock file and the
   script need to be updated — a clear violation of the single source of truth principle.

2. Committing skill files directly to the repo:
   Possible, but skills are generated dependencies — not source code. Committing them adds
   significant noise to diffs, bloats the repo, and makes updates manual. It's the equivalent
   of committing node_modules/.

3. Issue feat: Add .skills file support for declarative skill management #134 — .skills manifest file:
   That proposal introduces a new file format for declarative skill installation. This
   feature request is different and complementary: it proposes using the existing
   skills-lock.json structure (no new format needed) to enable restoration, making it
   immediately useful without any additional configuration.

Additional Context

This is the last missing piece for teams treating skills as proper reproducible dependencies:

.gitignore

.cursor/skills/
.claude/skills/
.agents/skills/
.codex/skills/
.agents/skills/

skills-lock.json is committed ✅

onboarding / CI — one command:

npx skills install

Without this command, skills-lock.json is only useful for npx skills update on machines
that already have the skills installed. It provides zero value for fresh clones, new team
members, or clean CI runners.

This pattern is well-established: npm/yarn/pnpm/bun all use a lock file as the restore mechanism, not just as an update tracker. Skills should be no different.

Related issues:

• feat: Add .skills file support for declarative skill management #134 — .skills manifest (different approach, new format)
• Feature: support npx skills update for project-scoped installations #337 — project-scoped skills not tracked in lock (a prerequisite for full project-scope support)
• [Bug]: npx skills update fails silently for all skills (via npx on macOS) #371 — npx skills update fails silently (same root: update assumes skills exist)

[oneyoung19]

Good Job. This is actually what i want too.

[ramongarver]

Just wanted to share that npx skills experimental_install (available today) already covers step 2 of the restore workflow described here — it reads skills-lock.json and installs all skills from scratch on a fresh clone.

So while a fully-featured npx skills install with all the proposed options (scopes, --force, CI strict mode, etc.) is still worth building, the experimental_install command unblocks teams in the meantime.

We're already using it in our conductor.json setup script:

{
  "scripts": {
    "setup": "npx skills experimental_install"
  }
}

If you're using Bun, bunx skills experimental_install works even better 😊

Hope that helps anyone hitting this issue today!

[oneyoung19]

experimental_install

Thx a lot. I tried pnpx skills experimental_install which is based on nodejs, and it worked!

[travischapman]

So while a fully-featured npx skills install with all the proposed options (scopes, --force, CI strict mode, etc.) is still worth building, the experimental_install command unblocks teams in the meantime.

@ramongarver unfortunately it does not create symlinks for Claude Code (unless I'm using it wrong). That does mean if any dev on the team uses Claude Code, they'll need to manage those symlinks for the time being.

[nedtwigg]

I am also having the issue where experimental_install brings them back for Codex but not for Claude. Fwiw here's my workaround: ./install-skills.sh

#!/bin/bash
set -e
cd "$(dirname "$0")"
npx skills experimental_install
mkdir -p .claude/commands
for skill in .agents/skills/*/; do
  name="$(basename "$skill")"
  ln -sfn "../../.agents/skills/$name" ".claude/commands/$name"
  ln -sf "../../.agents/skills/$name/SKILL.md" ".claude/commands/$name.md"
done

[kchaengsiri]

Thanks! the bunx skills experimental_install works well for me!

[meleyal]

Will install support the --agent flag to only install for specific agents?

[jlguenego]

why not using the sha commit hash in the lock file ? It would allow the bunx skills install to retrieve exactly the right skill version from a repo.

[tlmader]

why not using the sha commit hash in the lock file ? It would allow the bunx skills install to retrieve exactly the right skill version from a repo.

Any updates on this? We are currently forced to commit all our skill installations.