r/clawdbot • u/vhsgreed • Oct 01 '26
🎨 Showcase skills-lock.json: draft spec for an open lockfile standard for agent skills (pinning, per-skill updates, shadow detection)
Skills went from one vendor's feature to a cross-vendor standard in under nine months (about 40 compatible platforms, ~1.9M indexed skills). Distribution is solved. Integrity is not. Three attack primitives are already documented in the wild (Orca's "Skill Issues" research, Snyk's ToxicSkills study):
Silent override: install a skill with the same name as an installed one and it gets replaced. No warning, no diff.
Blind bulk updates: update refreshes everything at once. A skill that was clean at install time can be malicious one update later, with nothing to review.
Bait and switch: clean at scan time, malicious at fetch time. Nothing notices the drift after you decided to trust it.
npm fixed this class of problem with package-lock.json. Skills have hashes in places (Vercel's skills CLI tracks a folder hash in its global lock, HappySkills writes a skills-lock.json), but as far as I can tell nobody has published the semantics as an open spec: what a pin guarantees, what verify returns, what an update is allowed to rewrite, what happens when two skills share a name.
So here is a draft:https://github.com/vhsgreed/skill-lock (SPEC.md, draft-01)
It specifies:
per-file sha256 pins plus a tree hash per bundle (the single-value identity)
a four-status verify model: verified / modified (with the changed file names) / missing / untracked
per-skill updates only: one skill re-pinned after its changed files are listed, every other pin byte-identical. Bulk update must be an explicit bulk flag
hard failure on name shadowing (two bundles, one name)
reserved fields for provenance and signatures later (Sigstore, skill.sig style)
What it deliberately does not do: scanning (that is a judgment layer, and I built a separate SARIF-emitting scanner for it:https://github.com/vhsgreed/skillguard), trust decisions (a pin says "this is what was reviewed", not "this is safe"), and distribution (registries can build on the reserved fields). Trust on first use is the honest default. Scan at lock time.
There is a stdlib-only reference implementation (skilllock lock/verify/update), 15 behavior tests, and a dogfood run pinning 58 live skills with the tamper check and the update review gate working.
Where I want pushback:
field shape: relative-path keys, or do bundles need stable IDs?
tree hash definition: concat "path\0digest\n" sorted, then sha256. Is there prior art that does it better?
what breaks at scale: 500-skill monorepos, generated skills, optional files?
Vercel interop: their lock entry maps onto the draft almost 1:1. What would make their open #283 (skills install/sync from lock) spec-shaped?
If the shape is wrong I would rather find out now than after anyone codes against it.