---
type: reference
title: Skills CLI Lock File System
description: Version pinning and update checking via global and local lock files (.skill-lock.json and skills-lock.json).
tags:
  - unverified
  - skills
  - lockfile
  - versioning
timestamp: 2026-07-18
verified: 2026-08-28
---

# Lock File System

The `skills` CLI uses a lock file system for version pinning and update checking.

## Lock File Locations

| Type | Path | Scope |
|------|------|-------|
| **Global lock** | `~/.agents/.skill-lock.json` | Global (user-wide) |
| **Local lock** | `skills-lock.json` | Project (checked into version control) |

## How `skills check` and `skills update` Work

1. Read `~/.agents/.skill-lock.json` for installed skills
2. Filter to GitHub-backed skills that have both `skillFolderHash` and `skillPath`
3. For each skill, call `fetchSkillFolderHash(source, skillPath, token)`
   - Optional auth token from `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`
4. `fetchSkillFolderHash` calls GitHub Trees API (`/git/trees/<branch>?recursive=1` for `main`, then `master` fallback)
5. Compare latest folder tree SHA with lock file `skillFolderHash`; mismatch means update available
6. `skills update` reinstalls changed skills by invoking the current CLI directly

## Lock File Format

- **Version:** v3
- **Key field:** `skillFolderHash` — GitHub tree SHA for the skill folder
- **Compatibility:** If reading an older lock file version, it is wiped. Users must reinstall skills to populate the new format.

## Related

* [Commands](/tools/vercel-labs-skills/commands.md) — check, update, experimental_install