Files
skillshare/website/docs/reference/commands/update.md
T
Willie 0793ebe3c6 fix(update): fail tracked repos whose git status cannot be read
update discarded the error from the uncommitted-changes check, so a repo
whose git status could not be read was treated as clean and pulled over
whatever local edits it had. It now fails that repo with "failed to check
git status: <err>" unless --force, matching uninstall and the Web API.
Batch update counts these as failed instead of skipped and exits non-zero.
2026-09-30 02:22:48 +08:00

468 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
sidebar_position: 2
---
# update
Update one or more skills or tracked repositories to the latest version.
```bash
skillshare update my-skill # Update single skill
skillshare update a b c # Update multiple at once
skillshare update --group frontend # Update all skills in a group
skillshare update team-skills # Update tracked repo
skillshare update --all # Update everything
skillshare update agents --all # Update all tracked/updatable agents
```
## When to Use
- A tracked repository has new commits (found via `check`)
- An installed skill has a newer version available
- You want to re-download a skill from its original source
```text
$ skillshare update pdf
Updating
─────────────────────────────────────────
▸ Source ~/.config/skillshare/skills
│
└─ Items 0 tracked repo(s), 1 skill(s)
│
├─ Skill pdf
│
├─ Source github.com/anthropics/skills/skills/pdf
│
└─ ✓ SUCCESS Updated successfully (1.9s)
- Audit Findings
→ risk: CLEAN
- Next Steps
→ Run 'skillshare sync' to distribute changes
```
## What Happens
### For Tracked Repositories
```mermaid
flowchart TD
TITLE["skillshare update _team-skills"]
S1["1. Check for uncommitted changes"]
S2["2. Run git pull"]
S3["3. Security audit gate"]
S4["4. Show changes"]
TITLE --> S1 -- clean --> S2 --> S3
S3 -- pass --> S4
S3 -- "At/above threshold" --> RB["Rollback"]
style RB fill:#ef4444,color:#fff
```
### For Regular Skills
```mermaid
flowchart TD
TITLE["skillshare update my-skill"]
S1["1. Read metadata"]
S2["2. Re-install from source"]
S3["3. Security audit gate"]
TITLE --> S1 --> S2 --> S3
```
## Options
| Flag | Description |
|------|-------------|
| `--all, -a` | Update all tracked repos/skills, or all agents when used as `update agents --all` |
| `--group, -G <name>` | Update all updatable skills in a group, or all agents in an agent subdirectory |
| `--force, -f` | Discard local changes and proceed despite audit findings |
| `--dry-run, -n` | Preview without making changes |
| `--skip-audit` | Skip the post-update security audit gate |
| `--audit-threshold <t>`, `--threshold <t>`, `-T <t>` | Override update audit block threshold (`critical|high|medium|low|info`; shorthand: `c|h|m|l|i`, plus `crit`, `med`) |
| `--diff` | Show file-level change summary after skill/repo update |
| `--audit-verbose` | Show detailed per-skill audit findings in batch mode |
| `--prune` | Remove stale skills (deleted upstream) instead of warning |
| `--project, -p` | Use project-level config in current directory |
| `--global, -g` | Use global config (`~/.config/skillshare`) |
| `--json` | Output as JSON |
| `--help, -h` | Show help |
`update agents` supports: `--all`, `--group`, `--force`, `--dry-run`, `--skip-audit`, `--audit-threshold` / `--threshold` / `-T`, `--json`, plus `--project` / `--global`. It does **not** support `--diff`, `--audit-verbose`, or `--prune`.
## JSON Output
```bash
skillshare update --all --json
```
```json
{
"updated": 3,
"skipped": 1,
"security_failed": 0,
"pruned": 0,
"dry_run": false,
"duration": "4.567s",
"items": [
{"name": "_team-skills", "type": "repo", "status": "updated"},
{"name": "my-skill", "type": "skill", "status": "updated"},
{"name": "another-skill", "type": "skill", "status": "updated"},
{"name": "local-only", "type": "skill", "status": "skipped"}
]
}
```
Possible `status` values: `updated`, `skipped`, `failed`, `security_blocked`. When an item fails, the `error` field is included.
When tracked repos are declared in metadata but missing on disk, each is reported as a skipped `repo` item with a concise `error` (`clone directory absent`), and an aggregated `missing_tracked_repos` summary carries the names plus a one-shot rehydration hint:
```json
{
"updated": 0,
"skipped": 1,
"items": [
{"name": "_team-skills", "type": "repo", "status": "skipped", "error": "clone directory absent"}
],
"missing_tracked_repos": {
"names": ["_team-skills"],
"hint": "Run 'skillshare install' to rehydrate tracked repositories"
}
}
```
The `missing_tracked_repos` field is omitted when no tracked repos are missing.
### Agent JSON Output
```bash
skillshare update agents --all --json
```
```json
{
"agents": [
{"name": "reviewer", "status": "updated", "source": "github.com/user/agents/reviewer.md"},
{"name": "team/tutor", "status": "up_to_date", "source": "github.com/user/agents/team/tutor.md"}
],
"dry_run": false,
"duration": "1.234s"
}
```
Possible agent `status` values include `updated`, `failed`, `skipped`, `up_to_date`, `update_available`, `dirty`, `drifted`, and `local`.
## Updating Agents
Use the `agents` kind selector when you only want to update standalone `.md` agents:
```bash
skillshare update agents reviewer
skillshare update agents --group team
skillshare update agents --all -T high
skillshare update agents --all --json
```
Agent updates follow the same audit gate as skills:
- tracked agent repos run `git pull`, then audit the updated repo
- metadata-backed single-file agents reinstall from source, audit the staged `.md`, and only replace the local file on success
## Update Multiple
Update several skills at once:
```bash
skillshare update skill-a skill-b skill-c
```
Only updatable skills (tracked repos or skills with metadata) are processed. Skills not found are warned but don't cause failure. However, if any skill is **blocked by the security audit gate**, the batch command exits with a non-zero code.
### Glob Patterns
Skill names support glob patterns (`*`, `?`, `[...]`) for batch operations:
```bash
skillshare update "core-*" # Update all skills matching core-*
skillshare update "_team-?" # Single-character wildcard
skillshare update "core-*" "util-*" # Multiple patterns
```
Glob patterns match against the **basename** (last path component) of each skill or tracked repo. For example, `"react-*"` matches `frontend/react-hooks` because the basename is `react-hooks`.
Glob matching is case-insensitive: `"Core-*"` matches `core-auth`, `CORE-DB`, etc.
:::tip Shell glob protection
Always quote glob patterns (`"core-*"`) to prevent your shell from expanding `*` into file names in the current directory.
:::
## Update Group
Update all updatable skills within a group directory:
```bash
skillshare update --group frontend # Update all in frontend/
skillshare update -G frontend -G backend # Multiple groups
skillshare update x -G backend # Mix names and groups
```
Local skills (without metadata or `.git`) inside the group are silently skipped.
A positional argument that matches a group directory (not a repo or skill) is auto-expanded:
```bash
skillshare update frontend # Same as --group frontend
# ℹ 'frontend' is a group — expanding to 3 updatable skill(s)
```
:::note
`--all` cannot be combined with skill names or `--group`.
:::
## Update All
Update everything at once:
```bash
skillshare update --all
```
This updates:
1. All tracked repositories (git pull)
2. All skills with source metadata (re-install)
### Example Output
```
Updating 2 tracked repos + 3 skills
[1/5] ✓ _team-skills Already up to date
[2/5] ✓ _personal-repo 3 commits, 2 files
[3/5] ✓ my-skill Reinstalled from source
→ risk: LOW (12/100)
[4/5] ! other-skill has uncommitted changes (use --force)
[5/5] ✓ another-skill Reinstalled from source
── Summary ─────────────────────────────
Total: 5
Updated: 4
Skipped: 1
```
### Missing Tracked Repositories
If `.metadata.json` declares a tracked repo (`tracked: true`) but its clone directory is absent on disk — common on a fresh machine, since clone directories live in the managed `.gitignore` block — `update --all` no longer skips it silently. It reports each missing repo and points you to rehydrate:
```
! 1 tracked repo(s) declared in metadata but missing on disk:
! _team-skills clone directory absent
→ Run 'skillshare install' to rehydrate tracked repositories
```
This applies to both global and project (`-p`) mode. To recreate the clones from metadata, run no-argument [install](/docs/reference/commands/install) (see [Rehydrating After a Fresh Clone](/docs/understand/tracked-repositories#rehydrating-after-a-fresh-clone)).
## Stale Skill Cleanup (`--prune`)
When an upstream repository renames or removes a skill, `update` detects it as **stale** and warns you:
```
⚠ 1 skill(s) no longer found in upstream repository:
⚠ frontend/old-skill — stale (deleted upstream)
ℹ Run with --prune to remove stale skills
```
Add `--prune` to automatically remove stale skills (moved to trash, not permanently deleted):
```bash
skillshare update --all --prune
```
`check` also reports stale skills:
```bash
skillshare check --all
# ⚠ 1 skill(s) stale (deleted upstream) — run 'skillshare update --all --prune' to remove
```
:::note
Tracked repositories (`_repo`) are not affected by `--prune`. When a tracked repo removes a skill internally, `sync` automatically cleans up orphan symlinks via `PruneOrphanLinks`.
:::
## Security Audit Gate {#security-audit-gate}
After updating skills, `update` automatically runs a security audit:
- **Tracked repos (`git pull`)** use a post-pull gate at the active threshold (`audit.block_threshold`, default `CRITICAL`)
- **Regular skills (reinstall path)** use the same threshold policy
- For all update types, risk label/score is displayed for review context
```
→ risk: LOW (12/100)
```
### Interactive Mode (TTY, tracked repos)
When findings are detected at or above the active threshold, you're prompted to decide:
```
[HIGH] Source repository link detected — may be used for supply-chain redirects (SKILL.md:5)
Security findings at or above active threshold detected.
Apply anyway? [y/N]:
```
- **`y`** — Accept the update despite findings
- **`N`** (default) — Roll back to the pre-pull state
### Non-Interactive Mode (CI/CD)
In non-interactive environments, the update is automatically rolled back and the command exits with a non-zero code. This ensures fail-closed behavior in CI pipelines.
```bash
# Bypass the audit gate when you trust the source
skillshare update --all --skip-audit
```
:::caution
`--skip-audit` disables the post-update security scan entirely. Use it only when you trust the source or have an external audit process.
:::
### Accepted Findings {#accepted-findings}
When you override the gate with `--force` (or answer `y` at the prompt), the findings you accepted are recorded in `.metadata.json` under `audit_accepted`. Later updates of the same skill no longer block on those exact findings, so you do not have to repeat `--force` on every `update --all`.
```
ℹ 1 previously accepted finding(s) skipped
```
A finding is matched by rule, file, and matched text — not by line number — so it stays accepted when unrelated content shifts. Any new finding, or the same rule matching different text, blocks again. This suits skills that legitimately quote attack strings as examples (security scanners, red-team docs) while still catching new payloads in later versions.
You can override threshold per command with `--audit-threshold`, `--threshold`, or `-T`:
```bash
skillshare update _team-skills --threshold high
skillshare update --all -T h
```
## File Change Summary (`--diff`)
Use `--diff` to see a file-level change summary after each update:
```bash
skillshare update team-skills --diff
skillshare update --all --diff
```
For **tracked repositories**, the diff uses `git diff` and includes line-level statistics:
```
┌─ Files Changed ─────────────────────────────┐
│ │
│ ~ SKILL.md (+12 -3) │
│ + scripts/deploy.sh (+45 -0) │
│ - old-helper.sh (+0 -22) │
│ ~ utils/format.md (+5 -2) │
│ │
└─────────────────────────────────────────────┘
```
For **regular skills** (installed from a remote source), the diff compares file hashes before and after the reinstall:
```
┌─ Files Changed ─────────────────────────────┐
│ │
│ ~ SKILL.md │
│ + new-helper.sh │
│ │
└─────────────────────────────────────────────┘
```
Markers: `+` added, `-` deleted, `~` modified. Shows up to 20 files; additional files are summarized as "... and N more file(s)".
## Handling Conflicts
If a tracked repo has uncommitted changes:
```bash
# Option 1: Commit your changes first
cd ~/.config/skillshare/skills/_team-skills
git add . && git commit -m "My changes"
skillshare update _team-skills
# Option 2: Discard and force update
skillshare update _team-skills --force
```
If skillshare cannot read the repo's git status, the update fails for that repo with `failed to check git status`; `--force` skips the check.
## After Updating
Run `skillshare sync` to distribute changes to all targets:
```bash
skillshare update --all --diff # Update with file-level change summary
skillshare sync
```
## Project Mode
Update skills and tracked repos in the project:
```bash
skillshare update pdf -p # Update single skill (reinstall)
skillshare update a b c -p # Update multiple skills
skillshare update --group frontend -p # Update all in a group
skillshare update team-skills -p # Update tracked repo (git pull)
skillshare update --all -p # Update everything
skillshare update --all -p --dry-run # Preview
skillshare update --all -p --diff # Update with file change summary
skillshare update --all -p --skip-audit # Skip security audit gate
```
### How It Works
| Type | Method | Detected by |
|------|--------|-------------|
| **Tracked repo** (`_repo`) | `git pull` | Has `.git/` directory |
| **Remote skill** (with metadata) | Reinstall from source | Listed in `.metadata.json` |
| **Local skill** | Skipped | Not listed in `.metadata.json` |
The `_` prefix is optional — `skillshare update team-skills -p` auto-detects `_team-skills`.
### Lockfile
`update -p` is how a pinned commit moves forward. Each skill or tracked repo that lands on a new commit gets its entry in `.skillshare/skills.lock.json` rewritten; skills that did not change keep their pin. Commit the lockfile so teammates get the same commit on their next `skillshare install -p`. See [Lockfile](/docs/understand/project-skills#lockfile).
### Handling Conflicts
Tracked repos with uncommitted changes are blocked by default:
```bash
# Option 1: Commit changes first
cd .skillshare/skills/_team-skills
git add . && git commit -m "My changes"
skillshare update team-skills -p
# Option 2: Discard and force update
skillshare update team-skills -p --force
```
If skillshare cannot read the repo's git status, the update fails for that repo with `failed to check git status`; `--force` skips the check.
### Typical Workflow
```bash
skillshare update --all -p
skillshare sync
git add .skillshare/ && git commit -m "Update remote skills"
```
## See Also
- [install](/docs/reference/commands/install) — Install skills
- [upgrade](/docs/reference/commands/upgrade) — Upgrade CLI and built-in skill
- [sync](/docs/reference/commands/sync) — Sync to targets
- [Project Skills](/docs/understand/project-skills) — Project mode concepts