Why AI agent skills need a lockfile

Package managers pin dependencies twice: once by version, once by content hash. The version tells you what you asked for. The hash tells you what you actually got. The second one is what stops a republished, tampered or force-pushed artifact from slipping in.

Agent skills skipped that step. Most are installed by cloning a repo or copying a folder from main. That leaves three gaps.

Refs move

A branch is a pointer. main today is not main next week. Tags can be deleted and recreated. If your install command names a ref, your agent runs whatever that ref points to at install time.

Installed copies drift

Skills sit in plain folders like .claude/skills. Anyone, or any agent with write access, can edit them in place. Without a recorded hash, nothing notices.

Reviews expire

A security review applies to specific bytes. Once those bytes change, the review says nothing about the new version. Researchers have also shown that static scanners can be evaded, so a one-time scan is weak protection on its own.

What a skill lockfile records

• The source and the ref you requested
• The commit that ref resolved to
• A SHA-256 over every file path and file hash in the skill
• The scan grade at lock time

With that, install refuses content that does not match, verify catches local edits, and update shows exactly which skills moved and how their grades changed. The format is documented in skills.toml and skills.lock.

Skillhash is one implementation, open to use from the command line for free: uvx skillhash init.