Skip to main content
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: 
{
  "skills": [
    {
      "name": "frontend-design",
      "source": "vercel-labs/agent-skills",
      "skillFolderHash": "a3f2c1d9e8b7..."
    },
    {
      "name": "skill-creator",
      "source": "vercel-labs/agent-skills",
      "skillFolderHash": "f9b0e1d2c3a4..."
    }
  ],
  "forceRefresh": true
}

​
Output

✓ All skills are up to date (2 checked)

​
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

$ 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

​
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
​
forceRefresh
boolean
If true, bypass cache and fetch fresh content from GitHubDefault: false
CLI always sends: true

​
Response Schema

​
updates
array
Array of skills with update information

​
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

{
  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

{
  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

skills check

​
Update Skills

skills update

Lock Files

Learn about lock file structure and the skillFolderHash field

Telemetry

See what data is tracked and how to disable it

Build docs developers (and LLMs) love

Get started for freeTalk to us