skills update

Update all skills to latest versions

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

All Up to Date

$ skills update

Checking for skill updates...

✓ All skills are up to date

$ skills update

Checking for skill updates...

Found 3 update(s)

Updating frontend-design...
  ✓ Updated frontend-design
Updating web-design-guidelines...
  ✓ Updated web-design-guidelines
Updating skill-creator...
  ✓ Updated skill-creator

✓ Updated 3 skill(s)

$ skills update

Checking for skill updates...

Found 3 update(s)

Updating frontend-design...
  ✓ Updated frontend-design
Updating web-design-guidelines...
  ✗ Failed to update web-design-guidelines
Updating skill-creator...
  ✓ Updated skill-creator

✓ Updated 2 skill(s)
Failed to update 1 skill(s)

$ skills update

Checking for skill updates...

No skills tracked in lock file.
Install skills with npx skills add <package>

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:

Command	Purpose	Speed	Side Effects
skills check	Find updates	Fast (API only)	None (read-only)
skills update	Install updates	Slow (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:

Skill update fails

Behavior: Continues updating other skills

Result:

• 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)

Network issues

Behavior: Skips unreachable skills

Causes:

• GitHub API down
• Repository deleted/moved
• Network connectivity issues

Solution: Try again later or reinstall manually

Lock file write fails

Behavior: Update completes, but lock not updated

Impact: Next update may re-download same version

Solution: 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

Updates fail silently

Symptoms: Command runs but nothing updates

Causes:

• 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

Skill disappears after update

Symptoms: Skill not found after successful update

Cause: Skill was removed from source repository

Solution: Remove from lock file or pin to old version

skills remove --global skill-name

Update takes too long

Symptoms: Update hangs or is very slow

Causes:

• 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

Related Commands

• skills check - Check for updates without installing
• skills add - Install or reinstall skills manually
• skills list - List installed skills and their versions