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.

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.

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

• 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.