Skip to main content

​
Usage

skills check

​
Description

The check command compares your installed skills against the latest versions on GitHub to identify available updates. It uses GitHub’s Trees API to detect changes in skill folders without downloading files.
Only global skills installed with -g are tracked for updates. Project-scoped skills are not checked.

​
How It Works

1

Read Lock File

Reads ~/.agents/.skill-lock.json to get installed skill information including:
  • Skill source (owner/repo)
  • Skill path in repository
  • Current folder hash (GitHub tree SHA)
2

Fetch Latest Hashes

For each skill, fetches the latest folder hash from GitHub using the Trees API.The hash represents the entire skill folder’s state, so any change (files added, modified, or deleted) will result in a different hash.
3

Compare Versions

Compares current hash with latest hash:
  • Match: Skill is up to date
  • Different: Update available
4

Report Results

Shows:
  • Skills with updates available
  • Skills that are up to date
  • Skills that couldn’t be checked (errors)
  • Skills skipped (local paths, no version tracking)

​
Update Detection

Updates are detected by comparing GitHub tree SHAs: 
Current hash:  abc123... (from lock file)
Latest hash:   def456... (from GitHub API)
Result:        Update available
This approach:
  • ✅ Detects any changes to skill files
  • ✅ Works without downloading files
  • ✅ Leverages GitHub’s caching
  • ✅ Supports authenticated requests (higher rate limits)

​
GitHub Token

To avoid rate limits, set a GitHub personal access token: 
export GITHUB_TOKEN=ghp_your_token_here
skills check
The CLI will automatically use the token for GitHub API requests, providing:
  • Higher rate limits: 5,000 requests/hour (vs 60 for unauthenticated)
  • Access to private repositories: If your skills are in private repos

​
Output Examples

$ skills check

Checking for skill updates...

Checking 5 skill(s) for updates...

✓ All skills are up to date

​
Skills Not Checked

Some skills cannot be checked automatically:
Skills installed from local paths (./my-skill) cannot be checked for updates.Reason: No remote source to compare againstManual update:
npx skills add ./my-skill -g -y
Skills from non-GitHub Git URLs don’t support hash tracking yet.Reason: Trees API is GitHub-specificManual update:
npx skills add https://git.example.com/repo -g -y
Skills installed before lock file v3 don’t have folder hashes.Reason: Lock file was upgraded, missing metadataFix: Reinstall the skill
npx skills add owner/repo@skill -g -y
Skills without a recorded path in the lock file.Reason: Lock file corruption or old formatFix: Reinstall the skill
npx skills add owner/repo@skill -g -y

​
Lock File Format

The check command requires lock file version 3 (current): 
{
  "version": 3,
  "skills": {
    "frontend-design": {
      "source": "vercel-labs/agent-skills",
      "sourceType": "github",
      "sourceUrl": "https://github.com/vercel-labs/agent-skills",
      "skillPath": "skills/frontend-design/SKILL.md",
      "skillFolderHash": "abc123...",
      "installedAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}
Key fields for update checking:
  • source: Owner/repo format
  • skillPath: Path to SKILL.md in repository
  • skillFolderHash: GitHub tree SHA for the skill folder

​
Rate Limiting

​
Without Token

  • Limit: 60 requests per hour (per IP)
  • Scope: All unauthenticated GitHub API requests

​
With Token

  • Limit: 5,000 requests per hour
  • Scope: Per authenticated user
Best practice: Set GITHUB_TOKEN if you have many skills or check frequently.

​
Comparison with Update

The check and update commands work together:
CommandPurposeAction
skills checkFind updatesRead-only, shows what’s available
skills updateInstall updatesChecks AND reinstalls updated skills
Workflow: 
# Step 1: Check what needs updating
skills check

# Step 2: Apply updates
skills update
Or just run skills update directly - it checks first automatically.

​
Troubleshooting

Error: API rate limit exceededSolution: Set a GitHub token
export GITHUB_TOKEN=ghp_your_token
skills check
Message: No skills tracked in lock fileCause: No global skills installed, or lock file missingSolution: Install skills with -g flag
skills add vercel-labs/agent-skills -g
Message: Could not check N skill(s)Causes:
  • Network issues
  • Repository deleted or moved
  • Private repository without token
  • Skill path changed in repository
Solution: Try reinstalling
skills add owner/repo@skill -g -y

Build docs developers (and LLMs) love

Get started for freeTalk to us