explainx / blog
What project-level skills-lock.json records—GitHub sources, sourceType, computedHash—and why teams commit it for npx skills workflows, CI, and supply-chain hygiene.
May 6, 2026
Codex pets look whimsical; operationally they are a status surface for long agent runs. This guide goes settings-deep: Appearance & Pets, composer commands, hatch-pet packaging, art direction, and how to choose top built-in vs custom mascots without drowning in sprite tech debt.
May 2, 2026
What shipped in Codex’s agent UI, how custom pets are packaged through OpenAI’s hatch-pet skill, and why a little dock-side animation can still be a serious product bet.
Jun 28, 2026
Prompt engineering fixes your wording. Context engineering fixes what the model sees. This guide draws the precise line, shows concrete examples of each in action, and maps out when to reach for which tool.
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.
| Question | Short answer |
|---|---|
| What is it? | JSON manifest: skill name → source + computedHash, usually version: 1. |
| Why bother? | Reproducible installs across machines; reviewable list of third-party instruction packs. |
| Who writes it? | The npx skills / bunx skills CLI when you add skills in project scope. |
| Commit it? | Yes, for team repos—like locking npm deps—unless your org forbids checked-in tool state. |
| Upstream | vercel-labs/skills (docs, issues, evolving ci / verify story). |
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.
Agent skills are not magical—they are files (often SKILL.md plus assets) that coding agents load into context. Without a lockfile:
“run these three add commands in order”).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.
npx skills / bunx skills as documented upstream.skills-lock.json (and copies files into agent-specific dirs like .cursor/skills, .claude/skills, depending on host)..gitignore for large skill trees is a team choice; many teams commit the lock and ignore only local cache if the CLI creates one.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.
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:
computedHash changes.skills-lock.json is what you actually ship.apm.yml + lockfiles in another packaging storyCLI 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.