Skip to main content

​
Usage

skills update
skills upgrade

​
Description

The update command automatically checks for and installs the latest versions of all globally installed skills. It’s equivalent to running skills check followed by reinstalling each skill that has an update.
Only global skills installed with -g are updated. Project-scoped skills are not tracked for updates.

​
How It Works

1

Check for Updates

Reads ~/.agents/.skill-lock.json and compares each skill’s folder hash with the latest version on GitHub.This is the same process as skills check.
2

Identify Updates

Creates a list of skills where the current hash differs from the latest hash.
Found 3 update(s)
3

Reinstall Skills

For each skill with an update:
  1. Constructs the source URL with skill path
  2. Runs npx skills add <url> -g -y
  3. Tracks success/failure
4

Report Results

Shows:
  • Number of skills successfully updated
  • Number of skills that failed to update
  • Updated lock file with new hashes

​
Update Process

For each skill needing an update: 
# Example: Updating frontend-design
# Lock file has: skillFolderHash: "abc123..."
# GitHub has:    skillFolderHash: "def456..."

# Internally runs:
npx skills add https://github.com/owner/repo/tree/main/skills/frontend-design -g -y
The reinstallation:
  • ✅ Downloads latest files from GitHub
  • ✅ Preserves agent links (reinstalls to same agents)
  • ✅ Updates lock file with new hash
  • ✅ Maintains global installation

​
Output Examples

$ skills update

Checking for skill updates...

✓ All skills are up to date

​
Skills Not Updated

Some skills cannot be updated automatically (same as skills check):

Local Paths

Skills from local paths (./my-skill) are skipped.Manual update:
npx skills add ./my-skill -g -y

Git URLs

Non-GitHub Git URLs don’t support automatic updates yet.Manual update:
npx skills add https://git.example.com/repo -g -y

No Version Hash

Skills without a skillFolderHash in the lock file.Fix: Reinstall the skill
npx skills add owner/repo@skill -g -y

Missing Skill Path

Skills without a skillPath in the lock file.Fix: Reinstall the skill
npx skills add owner/repo@skill -g -y

​
GitHub Token

For better performance and private repository access, set a GitHub token: 
export GITHUB_TOKEN=ghp_your_token_here
skills update
Benefits:
  • Higher rate limits: 5,000 requests/hour (vs 60 unauthenticated)
  • Private repos: Access skills in private repositories
  • Faster: Avoids rate limit delays

​
Update URL Construction

The update process constructs URLs based on lock file data: 
// Lock file entry:
{
  "sourceUrl": "https://github.com/owner/repo",
  "skillPath": "skills/frontend-design/SKILL.md"
}

// Constructed URL:
https://github.com/owner/repo/tree/main/skills/frontend-design
This ensures:
  • ✅ Exact skill folder is updated (not the entire repo)
  • ✅ Correct branch is used (defaults to main)
  • ✅ Subpath is preserved

​
Lock File Updates

After successful update, the lock file is updated: Before: 
{
  "frontend-design": {
    "skillFolderHash": "abc123...",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
After: 
{
  "frontend-design": {
    "skillFolderHash": "def456...",
    "updatedAt": "2024-01-20T15:45:00Z"
  }
}

​
Comparison with Check

The check and update commands work together:
CommandPurposeSpeedSide Effects
skills checkFind updatesFast (API only)None (read-only)
skills updateInstall updatesSlow (downloads)Modifies files
When to use:
  • check: Quick check before committing, in CI, or before presentations
  • update: When you’re ready to update and have time for downloads

​
Error Handling

The update process is resilient:
Behavior: Continues updating other skillsResult:
  • Successful skills are updated
  • Failed skills show error messages
  • Lock file only updated for successful skills
✓ Updated 2 skill(s)
Failed to update 1 skill(s)
Behavior: Skips unreachable skillsCauses:
  • GitHub API down
  • Repository deleted/moved
  • Network connectivity issues
Solution: Try again later or reinstall manually
Behavior: Update completes, but lock not updatedImpact: Next update may re-download same versionSolution: Check file permissions on ~/.agents/.skill-lock.json

​
Best Practices

1

Check First

Run skills check before updating to see what will change:
skills check
skills update
2

Set GitHub Token

Avoid rate limits with a personal access token:
export GITHUB_TOKEN=ghp_your_token
Add to your shell profile for persistence.
3

Review Changes

After updating, review the skill changes:
skills list -g
Test skills with your agent before important work.

​
Troubleshooting

Symptoms: Command runs but nothing updatesCauses:
  • No global skills installed
  • All skills already up to date
  • Skills can’t be auto-updated (local/git)
Check:
skills list -g  # See what's installed
skills check    # See what needs updates
Symptoms: Skill not found after successful updateCause: Skill was removed from source repositorySolution: Remove from lock file or pin to old version
skills remove --global skill-name
Symptoms: Update hangs or is very slowCauses:
  • Large skill repositories
  • Slow network connection
  • Many skills to update
Solutions:
  • Use GitHub token for better rate limits
  • Update specific skills manually
  • Check network connection

​
Alias

The following alias is available:
  • skills upgrade → skills update

Build docs developers (and LLMs) love

Get started for freeTalk to us