skills-lock.json: reproducible agent skills for your repo (lockfile primer)

Project-level skills-lock.json is the agent-skills equivalent of a package lockfile: it records which skills your repo expects, where they came from, and a hash snapshot the npx skills toolchain can use for updates and—depending on CLI version—restore workflows.

This post explains the shape, why teams commit it, and links to the upstream CLI so you can verify current commands.

TL;DR

The on-disk shape (illustrative example)

A project-level skills-lock.json often looks like this (names, repos, and hashes are placeholders—your CLI will write real values):

{
  "version": 1,
  "skills": {
    "api-design-review": {
      "source": "example-org/agent-skills",
      "sourceType": "github",
      "computedHash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
    },
    "release-checklist": {
      "source": "example-org/agent-skills",
      "sourceType": "github",
      "computedHash": "fedcba09876543210fedcba09876543210fedcba09876543210fedcba0987654321"
    }
  }
}

How to read it:

• version — lockfile schema generation; parsers can branch on this.
• skills — map from install name → metadata.
• source — normalized GitHub coordinates (owner/repo) for remote pulls.
• sourceType — transport hint (github, and in other projects possibly local, mintlify, etc.).
• computedHash — fingerprint of the skill folder used by the CLI for update detection and integrity-style checks; the exact algorithm is defined in upstream local-lock code—see vercel-labs/skills.

Hashes will change when upstream maintainers update SKILL.md or bundled resources—treat bumps like dependency updates: review diffs.

Why lock skills at all?

Agent skills are not magical—they are files (often SKILL.md plus assets) that coding agents load into context. Without a lockfile:

• Onboarding is tribal knowledge (“run these three add commands in order”).
• CI and contractors get different skill versions.
• Supply-chain reviews are harder: you cannot diff skills in PRs the way you diff package.json.

With skills-lock.json, the intent is explicit: these packages of instructions are part of how this repo is meant to be edited.

This matters more for skills than it did for early package managers, because a skill is not compiled code—it is natural-language instructions an LLM reads and acts on directly. A subtly rewritten sentence in SKILL.md can change agent behavior in ways a code reviewer skimming a diff might miss entirely, unlike a dependency bump where a failing test suite usually catches the regression. The lockfile's job is to make sure that change is at least visible as a diff, even if catching its downstream effect still requires a human to actually read the new instructions.

Upstream discussion frames restoration via commands such as npx skills experimental_install / promoted skills ci—check the latest README before scripting CI, because flag names have moved quickly in 2026.

Operational playbook (high level)

1. Install the CLI — npx skills / bunx skills as documented upstream.
2. Add skills in project scope — writes or updates skills-lock.json (and copies files into agent-specific dirs like .cursor/skills, .claude/skills, depending on host).
3. Commit the lockfile — optional .gitignore for large skill trees is a team choice; many teams commit the lock and ignore only local cache if the CLI creates one.
4. Restore on clone — run the install-from-lock command your CLI version supports.
5. Verify in CI (when available) — proposals and shipped commands like skills verify compare disk ↔ lock; useful for “no silent edits to SKILL.md.”

Caveat: Hash semantics have been refined in issues such as “computedHash cannot be verified against installed files”—meaning you should treat computedHash as tool-defined, not a portable cryptographic standard, until your installed CLI version documents otherwise.

How skills-lock.json compares to other lockfiles

If you have ever debugged a package-lock.json merge conflict or waited on bun.lock to resolve a dependency graph, the mental model for skills-lock.json will feel familiar—but the thing being locked is different in a way worth spelling out.

That last distinction matters. A package lockfile pins a version identifier—npm, crates.io, and similar registries are append-only, so 1.4.2 always resolves to the same bytes. Agent skills, at least in the current vercel-labs/skills implementation, are pulled directly from GitHub repos rather than an immutable package registry. A maintainer can force-push, rewrite a tag, or simply edit SKILL.md on the default branch without bumping any version number at all. computedHash exists specifically to catch that case: it is a content fingerprint, not a semver pointer, so it changes the moment the underlying instructions change—even if nothing else about the "release" changed.

This is also why the skills ecosystem cannot simply reuse package-lock.json tooling wholesale. A JavaScript package manager assumes the registry guarantees immutability per version; skills-lock.json cannot make that assumption about an arbitrary GitHub repo, so it has to re-derive integrity from content hashing instead of trusting a version string.

A multi-skill lockfile, end to end

Real projects rarely install a single skill. Here is a more representative skills-lock.json for a repo pulling in several skills from different sources, to show how the shape scales:

{
  "version": 1,
  "skills": {
    "frontend-design": {
      "source": "whyashthakker/design-md-templates-skills",
      "sourceType": "github",
      "computedHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a1"
    },
    "seo-geo": {
      "source": "whyashthakker/design-md-templates-skills",
      "sourceType": "github",
      "computedHash": "3608bd35a71b13b7d1e9be0b7a2f2b0e1c9d2e5a4b1c8f7e6d5c4b3a2918f7e6"
    },
    "api-design-review": {
      "source": "example-org/agent-skills",
      "sourceType": "github",
      "computedHash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
    }
  }
}

Notice that two skills can share the same source repo—a single GitHub repository is free to host multiple named skills in subdirectories, and the lockfile tracks each installed skill independently by its own computedHash. When you run an update command, the CLI recomputes the hash for each entry against the current upstream content and flags only the ones that actually changed, rather than treating the whole lockfile as one atomic unit.

What a hash mismatch looks like in practice

When computedHash in your lockfile no longer matches what the CLI recomputes from the live source, you get a drift warning rather than a silent overwrite—the point of the lockfile is to surface the change for review, not to auto-apply it. A typical workflow when that happens:

1. Diff the change — most CLI versions can show you what changed in SKILL.md between the locked hash and the current upstream content, the same way you'd read a git diff before merging a dependency bump.
2. Decide: accept or pin — if the change is a legitimate improvement (better examples, a fixed typo, an added edge case), accept it and let the CLI rewrite computedHash. If it looks unrelated to what you expect from that skill, or introduces instructions you did not review, hold off and investigate the source repo's commit history first.
3. Re-commit the updated lockfile — same discipline as running npm install after bumping a dependency: the lockfile change should be its own reviewable diff in the PR, not bundled silently into an unrelated commit.

This review loop is the actual value of the lockfile. Without it, a skill silently changing underneath you is indistinguishable from a skill that has always behaved that way—there's no diff to point at, no PR to review, and no way to know your agent's instructions changed at all.

Wiring skills-lock.json into CI

Once a lockfile exists, the natural next step is making CI enforce it—failing a build when the checked-out SKILL.md files don't match what's recorded in skills-lock.json. This is the same principle as npm ci refusing to proceed when package-lock.json and package.json disagree, applied to instruction files instead of dependencies.

A representative GitHub Actions step, written against the direction the upstream CLI has been moving toward (verify exact flag names against the README before scripting this into a required check):

- name: Verify agent skills match lockfile
  run: |
    npx skills install --frozen-lockfile
    # or, once available in your installed CLI version:
    # npx skills verify

The --frozen-lockfile-style flag (again, naming varies by CLI version) is the important part conceptually: it should refuse to silently update skills-lock.json during a CI run, and instead fail loudly if what's on disk doesn't match what's recorded. That failure is a signal worth taking seriously—it means either someone hand-edited a skill file locally without updating the lock, or an upstream source changed between when the lockfile was last committed and when CI ran.

Treat a CI failure here the same way you'd treat a lockfile mismatch in npm ci: don't reflexively regenerate the lock to make the error go away. Pull the diff, understand what changed, and only then decide whether to accept the new hash.

Migrating an existing project without a lockfile

Most teams don't start with skills-lock.json—they adopt it after already having a handful of skills installed ad hoc (copied manually, or added before the lockfile convention existed on the project). The migration path is straightforward:

1. Inventory what's already installed. Check .claude/skills, .cursor/skills, or wherever your agent host stores skill files, and note which ones are actually in active use versus leftover experiments.
2. Re-add each skill through the CLI rather than hand-writing the lockfile. Running npx skills add owner/repo for each one lets the tool compute computedHash correctly instead of you guessing at the hash algorithm.
3. Diff before committing. Compare the freshly generated skills-lock.json against what was actually on disk pre-migration—this is a good moment to catch a skill that had drifted from its source without anyone noticing, since the hash comparison will surface it immediately.
4. Delete stale, unreferenced skill directories. A lockfile only tracks what it knows about; leftover skill folders that never went through the CLI won't appear in skills-lock.json and will silently persist as untracked instruction files unless you clean them up as part of the same migration pass.

Governance and security

A lockfile does not replace reading SKILL.md. Malicious or sloppy skills remain a real risk (OWASP Agentic Skills Top 10 is a practical checklist).

Recommended habits:

• Pin skills from orgs you trust; prefer repos you can audit.
• Review SKILL changes in PRs when computedHash changes.
• Separate “registry discovery” from “repo lock”—browsing explainx.ai/skills is discovery; skills-lock.json is what you actually ship.

Related on explainx.ai

• Comp AI agentic CRM — four versioned research skills on Eve
• What are agent skills? — mental model and ecosystem map
• Microsoft APM and portable skill manifests — apm.yml + lockfiles in another packaging story
• Agent skills security — threat framing
• Context engineering and clean prompts — skills + structured prompting together

Sources

• Upstream CLI & lockfile: github.com/vercel-labs/skills
• Hash / verify discussion: Issue #806 — computedHash vs installed layout
• Restore / CI direction: Issue #549 — install from lock, Issue #500 — lockfile enhancements
• Registry browsing: explainx.ai/skills

CLI flags and lockfile schema versions change frequently. Treat this article as May 12, 2026 context and re-read the vercel-labs/skills README before locking your build pipeline.