Lock Files

Understanding global and local lock file formats and structure

The Skills CLI uses two types of lock files to track installed skills: a global lock file for user-wide installations and a local lock file for project-scoped installations.

Global Lock File

The global lock file tracks all skills installed to your user directory (~/.agents/). It is located at:

~/.agents/.skill-lock.json

File Structure

Global Lock File Example

{
  "version": 3,
  "skills": {
    "frontend-design": {
      "source": "vercel-labs/agent-skills",
      "sourceType": "github",
      "sourceUrl": "https://github.com/vercel-labs/agent-skills",
      "skillPath": "skills/frontend-design",
      "skillFolderHash": "a3f2c1d9e8b7...",
      "installedAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:00.000Z",
      "pluginName": "web-design-tools"
    }
  },
  "dismissed": {
    "findSkillsPrompt": true
  },
  "lastSelectedAgents": ["claude-code", "cursor"]
}

Schema Fields

version · number · required

Schema version for future migrations. Current version is 3.

skills · object · required

Map of skill name to skill entry. Each entry contains:

Show SkillLockEntry

source · string · required

Normalized source identifier (e.g., "owner/repo", "mintlify/bun.com")

sourceType · string · required

Provider/source type:

• "github" - GitHub repository
• "mintlify" - Mintlify documentation
• "huggingface" - HuggingFace repository
• "local" - Local filesystem path

sourceUrl · string · required

Original URL used to install the skill (for re-fetching updates)

skillPath · string

Subpath within the source repo (e.g., "skills/react-best-practices")

skillFolderHash · string · required

GitHub tree SHA for the entire skill folder. This hash changes when ANY file in the skill folder changes. Fetched via GitHub Trees API.

installedAt · string · required

ISO 8601 timestamp when the skill was first installed

updatedAt · string · required

ISO 8601 timestamp when the skill was last updated

pluginName · string

Name of the plugin this skill belongs to (if any)

dismissed · object

Tracks dismissed prompts so they’re not shown again.

Show DismissedPrompts

findSkillsPrompt · boolean

Whether the find-skills skill installation prompt was dismissed

lastSelectedAgents · string[]

Array of agent IDs last selected for installation

Version History

Version 3 (Current)

Added skillFolderHash field for folder-based update detection.

Breaking change: Lock files from v2 and earlier are automatically wiped when read. Users must reinstall skills to populate the new format.

Version 2 (Deprecated)

Used content hashing for update detection.

Version 1 (Deprecated)

Initial version.

Skill Folder Hash Calculation

The skillFolderHash is a GitHub tree SHA computed by the GitHub API. It represents the state of the entire skill folder.

1. Request tree data

   The CLI calls GitHub’s Trees API for the repository:

   GET https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1
   
2. Find skill folder

   The response contains all files/folders. The CLI finds the tree entry matching the skill folder path.

3. Extract SHA

   The tree entry’s sha field is the skill folder hash. This SHA changes whenever any file in the folder changes.

For root-level skills (no subpath), the root tree SHA is used.

GitHub Token Resolution

To avoid rate limits, the CLI attempts to use a GitHub token in this order:

1. GITHUB_TOKEN environment variable
2. GH_TOKEN environment variable
3. gh CLI auth token (via gh auth token)

If no token is found, unauthenticated requests are made (lower rate limits apply).

---

Local Lock File

The local lock file tracks skills installed to a project directory. It is located at:

./skills-lock.json

This file is meant to be checked into version control and shared with your team.

File Structure

Local Lock File Example

{
  "version": 1,
  "skills": {
    "frontend-design": {
      "source": "vercel-labs/agent-skills",
      "sourceType": "github",
      "computedHash": "e8a9f1c2d3b4..."
    },
    "skill-creator": {
      "source": "../my-local-skills",
      "sourceType": "local",
      "computedHash": "f9b0e1d2c3a4..."
    }
  }
}

Design Philosophy

The local lock file is intentionally minimal to:

• Minimize merge conflicts - Skills are sorted alphabetically, and no timestamps are stored
• Deterministic output - Same skills = same JSON every time
• Git-friendly - Two branches adding different skills produce non-overlapping keys that auto-merge cleanly

Schema Fields

version · number · required

Schema version for future migrations. Current version is 1.

skills · object · required

Map of skill name to skill entry. Sorted alphabetically by key when written.

Show LocalSkillLockEntry

source · string · required

Where the skill came from:

• npm package name
• GitHub owner/repo
• Local path

sourceType · string · required

Provider/source type:

• "github" - GitHub repository
• "node_modules" - npm package
• "local" - Local filesystem path

computedHash · string · required

SHA-256 hash computed from all files in the skill folder on disk.

Unlike the global lock which uses GitHub tree SHA, the local lock computes the hash from actual file contents.

Computed Hash Algorithm

The local lock file uses content-based hashing:

1. Collect all files

   Recursively read all files in the skill directory (excluding .git/ and node_modules/)

2. Sort by path

   Sort files alphabetically by relative path for deterministic hashing

3. Hash contents

   Create a SHA-256 hash from:

   • Each file’s relative path (to detect renames)
   • Each file’s content (binary or text)

Example Implementation

import { createHash } from 'crypto';
import { readdir, readFile } from 'fs/promises';
import { join, relative } from 'path';

async function computeSkillFolderHash(skillDir: string): Promise<string> {
  const files: Array<{ relativePath: string; content: Buffer }> = [];
  
  // Collect all files recursively
  await collectFiles(skillDir, skillDir, files);
  
  // Sort by relative path for determinism
  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
  
  // Hash path + content for each file
  const hash = createHash('sha256');
  for (const file of files) {
    hash.update(file.relativePath);
    hash.update(file.content);
  }
  
  return hash.digest('hex');
}

---

Working with Lock Files

Reading Lock Files

Global Lock

import { readSkillLock } from './skill-lock';

const lock = await readSkillLock();
console.log(lock.skills); // All installed global skills

import { readLocalLock } from './local-lock';

const lock = await readLocalLock();
console.log(lock.skills); // All project skills

Adding Skills

Global Lock

import { addSkillToLock } from './skill-lock';

await addSkillToLock('my-skill', {
  source: 'owner/repo',
  sourceType: 'github',
  sourceUrl: 'https://github.com/owner/repo',
  skillPath: 'skills/my-skill',
  skillFolderHash: 'abc123...'
});

import { addSkillToLocalLock, computeSkillFolderHash } from './local-lock';

const hash = await computeSkillFolderHash('/path/to/skill');

await addSkillToLocalLock('my-skill', {
  source: 'owner/repo',
  sourceType: 'github',
  computedHash: hash
});

Removing Skills

Global Lock

import { removeSkillFromLock } from './skill-lock';

const removed = await removeSkillFromLock('my-skill');
console.log(removed); // true if skill existed

import { removeSkillFromLocalLock } from './local-lock';

const removed = await removeSkillFromLocalLock('my-skill');
console.log(removed); // true if skill existed

---

Related Documentation

Update System

Learn how the update checking system uses lock files

Plugin Manifests

Discover how plugin manifests integrate with lock files