Update System

How skills check and update commands work under the hood

The Skills CLI provides automatic update checking for installed skills via the skills check and skills update commands. These commands use a remote API to detect changes in skill repositories.

Overview

The update system works by comparing the skill folder hash stored in your local lock file against the latest hash from the remote source (e.g., GitHub).

1. Read lock file

   The CLI reads ~/.agents/.skill-lock.json to get all installed skills and their current skillFolderHash values

2. Request fresh hashes

   POST skill metadata to the update API at https://add-skill.vercel.sh/check-updates with forceRefresh: true

3. Compare hashes

   The API fetches fresh content from GitHub, computes the latest folder hash, and compares it to the hash you provided

4. Return updates

   The API returns a list of skills with different hashes (updates available)

---

Check Command

The skills check command checks for available updates without installing them.

skills check

API Request

The CLI sends a POST request to the update API:

Request Body

{
  "skills": [
    {
      "name": "frontend-design",
      "source": "vercel-labs/agent-skills",
      "skillFolderHash": "a3f2c1d9e8b7..."
    },
    {
      "name": "skill-creator",
      "source": "vercel-labs/agent-skills",
      "skillFolderHash": "f9b0e1d2c3a4..."
    }
  ],
  "forceRefresh": true
}

{
  "updates": [
    {
      "name": "frontend-design",
      "source": "vercel-labs/agent-skills",
      "currentHash": "a3f2c1d9e8b7...",
      "latestHash": "b4e3d2c1a9f8...",
      "hasUpdate": true
    }
  ]
}

Output

No Updates

✓ All skills are up to date (2 checked)

✓ Checked 2 skills
  1 update available:
  
  • frontend-design (vercel-labs/agent-skills)

Run 'skills update' to install updates

---

Update Command

The skills update command checks for updates and automatically reinstalls any skills with available updates.

skills update

Workflow

1. Check for updates

   Same as skills check - POST to the API with current hashes

2. Confirm updates

   If updates are found, prompt the user to confirm (unless -y flag is passed)

3. Reinstall skills

   For each skill with an update:

   • Fetch the latest version from the source
   • Compute the new folder hash
   • Install to the same agents as before
   • Update the lock file with new hash and updatedAt timestamp
4. Report results

   Show success/failure count for updated skills

Example Session

Interactive

$ skills update
✓ Checked 3 skills
  1 update available:
  
  • frontend-design (vercel-labs/agent-skills)

? Update 1 skill? (Y/n) y

✓ Updated frontend-design

✓ 1 skill updated successfully

$ skills update -y
✓ Checked 3 skills
  1 update available
  
✓ Updated frontend-design

✓ 1 skill updated successfully

---

Force Refresh

Why forceRefresh: true?

Both skills check and skills update always send forceRefresh: true in the API request. This ensures the API fetches fresh content from GitHub rather than using its Redis cache.

Without forceRefresh: Users saw phantom “updates available” due to stale cached hashes. The fix was to always fetch fresh data.

Tradeoff

Slower

Requires a GitHub API call per skill instead of using cache

Accurate

Always reflects the true current state of the remote repository

Performance Considerations

For repositories with many skills:

• The API makes ONE GitHub Trees API call per repository (not per skill)
• Skills from the same repository share a single request
• Typical check time: 1-3 seconds for 10 skills across 3 repositories

---

Update API Endpoint

POST

https://add-skill.vercel.sh/check-updates

Request Schema

skills · array · required

Array of skill metadata objects

Show Skill Metadata

name · string · required

Skill name (from lock file key)

source · string · required

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

skillFolderHash · string · required

Current GitHub tree SHA from lock file

skillPath · string

Subpath within the repository (e.g., "skills/frontend-design")

forceRefresh · boolean

If true, bypass cache and fetch fresh content from GitHub

Default: false
CLI always sends: true

Response Schema

updates · array

Array of skills with update information

Show Update Entry

name · string

Skill name

source · string

Source identifier

currentHash · string

Hash from your lock file

latestHash · string

Latest hash from remote source

hasUpdate · boolean

true if hashes differ (update available)

---

Lock File Compatibility

Version 3 Required

The update system requires lock file version 3, which introduced the skillFolderHash field.

If you have an older lock file (v2 or earlier), it will be automatically wiped when the CLI reads it. You must reinstall skills to populate the new format.

Migration Path

1. Backup (optional)

   If you want to preserve skill names:

   cp ~/.agents/.skill-lock.json ~/.agents/.skill-lock.json.backup
   
2. Run any command

   Any CLI command will trigger the lock file wipe:

   skills list
   
3. Reinstall skills

   Reinstall your skills to populate the new lock file:

   skills add vercel-labs/agent-skills --skill frontend-design
   

---

How the API Works

The update API performs these steps for each skill:

1. Parse source

   Extract owner/repo from the source identifier

2. Fetch tree

   Call GitHub Trees API to get the entire repository tree:

   GET /repos/{owner}/{repo}/git/trees/{branch}?recursive=1
   
3. Find skill folder

   Locate the tree entry matching the skill path

4. Extract SHA

   Get the sha field from the tree entry (this is the folder hash)

5. Compare

   Compare the remote SHA with the hash from your request

6. Cache (optional)

   If forceRefresh: false, cache the result in Redis for 5 minutes

Rate Limiting

The API uses GitHub tokens to avoid rate limits:

• Authenticated requests: 5,000 requests/hour
• Unauthenticated requests: 60 requests/hour

The API automatically uses a GitHub token if available (server-side).

---

Telemetry

The update commands send anonymous telemetry to help improve the CLI:

Check Command

Tracked Data

{
  event: 'check',
  skillCount: '5',           // Number of skills checked
  updatesAvailable: '2',     // Number of updates found
  v: '1.2.3',               // CLI version
  ci: '0'                   // 1 if running in CI
}

Update Command

Tracked Data

{
  event: 'update',
  skillCount: '2',      // Number of skills with updates
  successCount: '2',    // Number successfully updated
  failCount: '0',       // Number that failed to update
  v: '1.2.3',          // CLI version
  ci: '0'              // 1 if running in CI
}

Telemetry can be disabled by setting DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1

---

Examples

Check for Updates

Basic Check

skills check

# Telemetry automatically disabled in CI
skills check

DISABLE_TELEMETRY=1 skills check

Update Skills

Interactive

skills update

skills update -y

DISABLE_TELEMETRY=1 skills update -y

---

Related Documentation

Lock Files

Learn about lock file structure and the skillFolderHash field

Telemetry

See what data is tracked and how to disable it