> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/skills/llms.txt
> Use this file to discover all available pages before exploring further.

# skills update

> Update all skills to latest versions

## Usage

```bash theme={null}
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`](/commands/check) followed by reinstalling each skill that has an update.

<Note>
  Only **global skills** installed with `-g` are updated. Project-scoped skills are not tracked for updates.
</Note>

## How It Works

<Steps>
  <Step title="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`](/commands/check).
  </Step>

  <Step title="Identify Updates">
    Creates a list of skills where the current hash differs from the latest hash.

    ```
    Found 3 update(s)
    ```
  </Step>

  <Step title="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
  </Step>

  <Step title="Report Results">
    Shows:

    * Number of skills successfully updated
    * Number of skills that failed to update
    * Updated lock file with new hashes
  </Step>
</Steps>

## Update Process

For each skill needing an update:

```bash theme={null}
# 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

<CodeGroup>
  ```bash All Up to Date theme={null}
  $ skills update

  Checking for skill updates...

  ✓ All skills are up to date
  ```

  ```bash Updates Available theme={null}
  $ 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)
  ```

  ```bash Partial Success theme={null}
  $ 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)
  ```

  ```bash No Skills theme={null}
  $ skills update

  Checking for skill updates...

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

## Skills Not Updated

Some skills cannot be updated automatically (same as [`skills check`](/commands/check)):

<CardGroup cols={2}>
  <Card title="Local Paths" icon="folder">
    Skills from local paths (`./my-skill`) are skipped.

    **Manual update:**

    ```bash theme={null}
    npx skills add ./my-skill -g -y
    ```
  </Card>

  <Card title="Git URLs" icon="git">
    Non-GitHub Git URLs don't support automatic updates yet.

    **Manual update:**

    ```bash theme={null}
    npx skills add https://git.example.com/repo -g -y
    ```
  </Card>

  <Card title="No Version Hash" icon="question">
    Skills without a `skillFolderHash` in the lock file.

    **Fix:** Reinstall the skill

    ```bash theme={null}
    npx skills add owner/repo@skill -g -y
    ```
  </Card>

  <Card title="Missing Skill Path" icon="map">
    Skills without a `skillPath` in the lock file.

    **Fix:** Reinstall the skill

    ```bash theme={null}
    npx skills add owner/repo@skill -g -y
    ```
  </Card>
</CardGroup>

## GitHub Token

For better performance and private repository access, set a GitHub token:

```bash theme={null}
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:

```javascript theme={null}
// 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:**

```json theme={null}
{
  "frontend-design": {
    "skillFolderHash": "abc123...",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
```

**After:**

```json theme={null}
{
  "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:

<AccordionGroup>
  <Accordion title="Skill update fails" icon="triangle-exclamation">
    **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)
    ```
  </Accordion>

  <Accordion title="Network issues" icon="wifi">
    **Behavior:** Skips unreachable skills

    **Causes:**

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

    **Solution:** Try again later or reinstall manually
  </Accordion>

  <Accordion title="Lock file write fails" icon="file">
    **Behavior:** Update completes, but lock not updated

    **Impact:** Next update may re-download same version

    **Solution:** Check file permissions on `~/.agents/.skill-lock.json`
  </Accordion>
</AccordionGroup>

## Best Practices

<Steps>
  <Step title="Check First">
    Run `skills check` before updating to see what will change:

    ```bash theme={null}
    skills check
    skills update
    ```
  </Step>

  <Step title="Set GitHub Token">
    Avoid rate limits with a personal access token:

    ```bash theme={null}
    export GITHUB_TOKEN=ghp_your_token
    ```

    Add to your shell profile for persistence.
  </Step>

  <Step title="Review Changes">
    After updating, review the skill changes:

    ```bash theme={null}
    skills list -g
    ```

    Test skills with your agent before important work.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Updates fail silently" icon="circle-question">
    **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:**

    ```bash theme={null}
    skills list -g  # See what's installed
    skills check    # See what needs updates
    ```
  </Accordion>

  <Accordion title="Skill disappears after update" icon="ghost">
    **Symptoms:** Skill not found after successful update

    **Cause:** Skill was removed from source repository

    **Solution:** Remove from lock file or pin to old version

    ```bash theme={null}
    skills remove --global skill-name
    ```
  </Accordion>

  <Accordion title="Update takes too long" icon="clock">
    **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
  </Accordion>
</AccordionGroup>

## Alias

The following alias is available:

* `skills upgrade` → `skills update`

## Related Commands

* [`skills check`](/commands/check) - Check for updates without installing
* [`skills add`](/commands/add) - Install or reinstall skills manually
* [`skills list`](/commands/list) - List installed skills and their versions