Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
44 lines
1.6 KiB
Markdown
44 lines
1.6 KiB
Markdown
---
|
|
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
|