* test(install): reproduce loss of pulled tracked records Exercise the two-machine push and pull sequence and reconciliation states so missing tracked clones cannot silently erase shared install intent. * fix(reconcile): preserve tracked records missing local clones Pull transfers tracked repository metadata but not ignored clones. Keep the missing records during global reconciliation so another install and push cannot erase shared intent or accepted audit findings on every machine. * test(reconcile): isolate tracked record fixtures Use the shared sandbox fixture for both reconciliation tests so their home and configuration paths remain isolated from the invoking environment. * fix(reconcile): retain all sourced tracked declarations Legacy tracked members and unfollowed source links can hide declarations from the local walk. Preserve sourced tracked records regardless of their path so unrelated installs cannot erase them or their audit acceptances. Document restoring a missing checkout before uninstalling it and cover migration, link collisions, aliases, and explicit removal. * test(reconcile): drop fixtures existing tests already pin The tracked-record unit test also seeded a missing plain record and a live plain record. TestReconcileGlobalSkills_PrunesStaleEntries already pins both outcomes: a sourced plain record whose folder is gone is pruned, and one on disk survives. The tracked record with no source still catches a fix that keeps everything or skips the prune. The two-machine test passed HOME and SKILLSHARE_CONFIG to RunCLIEnv, which already sets both from the sandbox for each child process. Separate homes, XDG paths, client overrides and git config remain. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(reconcile): retain tracked entry for unavailable link Expect sourced tracked declarations to survive reconciliation with either source-link policy, so the test matches the cross-machine retention contract. * fix(config): prune legacy tracked members Retain only sourced tracked repository declarations during reconciliation. Migrated member records are not restorable as repositories and retaining them would leave permanent misleading install requests and audit acceptances. * fix(reconcile): preserve tracked intent across followed links A source link can exist before a tracked repository declaration is pulled. Preserve that declaration when the linked folder is not a checkout so later reconciliation does not discard its record and audit acceptances. * test(reconcile): cover grouped followed declarations A followed group can contain the path of a pulled legacy repository declaration, which must retain its tracked intent while its key migrates. * fix(test): scope collision fixture runner correctly Keep the isolated CLI runner in the collision subtest that uses it so the integration test package can compile. * docs(manifest): clarify tracked checkout recovery A retained declaration cannot restore a checkout while another folder or source link occupies its destination, and restoration requires a reachable source. State those prerequisites in each manifest translation. * fix(config): prune members under recorded repositories A migrated underscore-named member can otherwise survive a missing checkout as a repository declaration. Check recorded ancestor paths while preserving ambiguous grouped declarations and unrelated aliases. * docs(manifest): restore fresh-clone project guidance Explain that project declarations without local install records remain available so teammates can install them after cloning. * refactor(reconcile): drop the tracked-intent walker policy Restore baseline normalization for present paths while retaining absent repository declarations through the shared metadata predicate. Isolate the reconcile fixtures without building a CLI and share native-client overrides without changing the original two-machine record and audit regression. Validation: gofmt, git diff --check and context-router check only. Runtime, builds and tests were not executed under the source-only gate. * fix: forget linked checkout records and declarations without checkouts Extend the metadata and uninstall owners to remove a declaration without reading or moving its occupant, contacting its source, or changing trash and gitignore. A failed metadata save makes every metadata-only result fail. Clean up global unlink records in CLI and API, preserve existing-path name precedence, report record-only results truthfully, and list declarations in the dashboard API with noCheckout. Keep project removal behavior unchanged. Remove the obsolete grouped-link walker-policy assertion while preserving grouped absent declarations and the original record/audit A/B regression. Validation: source-only five-pass review, gofmt, git diff --check and the context-router check. No runtime, builds, tests or frontend tooling ran. Stop at commit 15 for the mandatory Luna checkpoint before UI and docs work. * fix(server): reload metadata before removing declarations Preserve CLI records and audit acceptances written while the dashboard is open. Resolve new declarations from disk and refuse stale-cache saves after a reload failure, retaining unlink success when its link already moved. * feat(dashboard): remove a tracked repository record without a checkout Show declaration-only rows without checkout actions or status promises. Reuse Uninstall with record-specific confirmation and feedback, keep real-checkout force handling, and refresh the missing-entry list after repository removal or unlink. * docs: explain kept declarations and how to remove them Document direct global declaration removal and optional restore in English and all four translations, including occupied paths and normalization after reconcile. Keep built-in guidance accurate and use the existing API removal result for dashboard success feedback after concurrent CLI changes. * fix(dashboard): confirm restored checkouts after forceable refusals A tracked declaration can be restored through the CLI while its dashboard row still says there is no checkout. Treat a forceable uninstall refusal as evidence of the current checkout and promote the existing confirmation to its dirty or unreadable-status warning before allowing explicit force. Author stale-row regressions for both forceable codes before the source repair, and retain nonforceable failure and actual-result success feedback. Validation: five serial source review passes, git diff --check, and the context-router check. Tests, builds, runtime and frontend tooling were not run under the source-only gate. * test(server): persist overview declarations before routed request The overview fixture added declarations only to the in-memory skills store, which the real request's config reload replaced with on-disk metadata. The hosted unit, offline, and Nix jobs consequently returned no tracked rows. Save the complete fixture through MetadataStore before serving the request and fail setup on a save error. Keep the middleware, assertions, and production behavior unchanged. * fix(server): prefer exact declarations before checkout shorthand Removing a missing _team declaration from the dashboard could resolve the different org/_team checkout by basename and trash it instead. Reload metadata before declaration lookup, give exact declarations priority, and preserve checkout resolution before non-exact declaration fallback. Add routed absent/occupied regressions and checkout precedence guards, and persist existing checkout fixtures so the metadata reload keeps their state. Validation: gofmt, git diff --check, and context-router check passed. Tests were authored but not run under the source-only fleet restriction. * fix: preserve removal intent and report partial failures Bind dashboard record-only removal to its canonical declaration and refuse restored checkouts before checkout resolution or force. Refresh the row and require another confirmation before moving a restored checkout to trash. Keep unresolved uninstall inputs and their reasons in JSON failed results, including all-invalid requests, partial successes and dry runs. Report unlink metadata cleanup failures as partial results, refresh completed unlinks and show localized warnings. Keep CLI and dashboard guidance aligned. Regression tests were authored before source changes and remain unrun under the source-only task restriction. Static formatting, diff and router checks passed; no build, product runtime, frontend tooling or test suite was run. * fix(unlink): log partial metadata cleanup failures Write the unlink result after global metadata cleanup so load and save failures retain their diagnostic and report partial success. Preserve the successful link removal, warning, target and exit policy, and the existing link, project unlink and native removal failure behavior. Add the corrupt-metadata regression before the fix; leave it unrun under the source-only authorization. Formatting, diff and context-router checks pass; runtime verification remains with the coordinator. * fix(unlink): forget records below the removed link name Reconcile can normalize a followed link's record to untracked, and linked collections can retain nested repository declarations. Clean the removed namespace through the existing metadata path owner in both unlink callers, including audit acceptances, while keeping declaration uninstall strict. Author CLI and route regressions before the source fix for normalized and nested records, sibling preservation, and subsequent bare install. Tests remain unrun under the source-only task restriction; static checks only. * fix(uninstall): refuse a restored checkout at execution A declaration selected while absent can become a checkout before removal runs. Recheck the resolved source-relative name in the shared metadata-only execution owner and refuse before touching metadata, regardless of force. Reuse the existing dashboard conflict response and refresh/reselection flow for this refusal, preserving the earlier record-only intent guard. CLI results already carry shared execution failures through text and JSON. Author restoration, force, absent/occupied control and client boundary regressions before production edits. Correct the unlink fixture name and response-key assertion found in serial static review. All tests remain unrun under the source-only restriction; formatting/diff/router checks pass. * refactor(server): consolidate repository uninstall result handling Resolve a declaration or checkout to one item and canonical name before using the existing uninstall, conflict, log and success response tail. Keep metadata-only removal unforced, preserve its error and cache recovery behavior, and report movedToTrash from the selected item. Preserve exact declaration precedence, record-only checkout refusals, ordinary checkout errors and project behavior without changing tests. Five serial source review passes, gofmt, diff checks and the context-router check completed. Tests and builds remain unrun under the source-only brief. * fix(unlink): preserve independent records and trash undo metadata Limit unlink's legacy group matching to members so a retained declaration such as team/_repo survives unlinking _team. Share snapshot and removal matching while keeping generic uninstall's legacy contract unchanged. Save the exact removed records, audit acceptances and target overrides through uninstall's existing trash sidecar owner before pruning metadata. Keep metadata on sidecar failure and preserve completed-unlink warnings, fresh reloads, cache refresh and project-mode behavior. Author owner, CLI and API regressions for namespace collisions, undo, partial failures and project/empty controls. Source-only verification: gofmt, diff check and context-router check passed; runtime tests, builds, frontend checks and final make check remain unrun for root-owned gates. * fix(install): preserve independent tracked declarations Limit declaration-only cleanup to the precise namespace and legacy members already used by unlink. Keep independently installed prefixed repositories, their audit acceptances, and overrides when forgetting a missing checkout. * fix(cli): explain missing tracked repository recovery by mode Offer global record removal when restoring an unreachable source is unwanted. Keep project recovery scoped to install -p, share the hint with doctor, and align update documentation in every existing locale. * refactor(uninstall): share declaration and unlink operations Keep declaration resolution and unlink metadata ordering in shared owners so CLI and API preserve the same scope and recovery behavior. Consolidate domain regressions while retaining caller translation coverage. Distinguish record-only removals in API and CLI operation logs and CLI JSON, including mixed batches and dry runs. Document outcome fields, warning semantics, and current API error codes across existing locales. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Willie <egg358358@gmail.com>
19 KiB
sidebar_position
| sidebar_position |
|---|
| 2 |
update
Update one or more skills or tracked repositories to the latest version.
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
$ skillshare update pdf
✓ Update pdf · from github.com/anthropics/skills/skills/pdf · 1.9s
✓ Audit no findings
Next
skillshare sync link the changes into your targets
What Happens
For Tracked Repositories
flowchart TD
TITLE["skillshare update _team-skills"]
S1["1. Check for uncommitted changes"]
S2["2. Pull into isolated candidate"]
S3["3. Security audit gate"]
S4["4. Publish audited commit"]
TITLE --> S1 -- clean --> S2 --> S3
S3 -- pass --> S4
S3 -- "At/above threshold" --> RB["Reject; checkout unchanged"]
style RB fill:#ef4444,color:#fff
For Regular Skills
Skills installed from a remote source are reinstalled from it. Skills installed from a local path (skillshare install /path/to/skill) are re-copied from that path, so update picks up changes made there; check reports when that path has changed.
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. A tracked repo behind a followed source link is skipped with a warning, since it is your own checkout; update it by name |
--group, -G <name> |
Update all updatable skills in a group, or all agents in an agent subdirectory |
--force, -f |
Discard local changes, proceed despite audit findings, and reinstall remote skills that are already at the upstream commit |
--dry-run, -n |
Preview without making changes |
--skip-audit |
Skip the security audit gate |
--audit-threshold <t>, --threshold <t>, -T <t> |
Override update audit block threshold (`critical |
--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
skillshare update --all --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. A remote skill skipped for its local changes is a skipped item with "error": "local changes since install".
When a batch update finds remote skills already at the upstream commit, it leaves them alone and counts them in an up_to_date field. The field is omitted when the count is zero.
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:
{
"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 -g' to rehydrate tracked repositories, or 'skillshare uninstall <name> -g' to remove an unwanted declaration"
}
}
The missing_tracked_repos field is omitted when no tracked repos are missing.
Agent JSON Output
skillshare update agents --all --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, local, and error. An error agent could not be checked, for example because its remote is unreachable or its metadata is unreadable. The command then exits with a non-zero code instead of reporting the agents as up to date.
Updating Agents
Use the agents kind selector when you only want to update standalone .md agents:
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:
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:
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:
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:
skillshare update frontend # Same as --group frontend
# 'frontend' is a group — expanding to 3 updatable skills
:::note
--all cannot be combined with skill names or --group.
:::
Update All
Update everything at once:
skillshare update --all
This updates:
- All tracked repositories (git pull)
- All skills with source metadata (reinstall when upstream changed)
update --all and update --group group remote skills by repository and clone each repository once. They leave alone any skill whose folder did not change upstream and count it as up to date. A skill whose folder contains a symlink is the exception: its files can change without the folder changing, so it is reinstalled whenever the upstream commit moves. Several skills named in project mode (-p) work the same way. Use --force to reinstall every skill anyway. A single skill, and skills named in global mode, are always reinstalled. A skill whose files you changed since install is skipped in every case until you add --force (see Handling Conflicts). When a repository cannot be fetched, its skills count as skipped and update prints a warning naming the repository and the error, with any credentials in the URL removed.
Only one skillshare process updates a git checkout at a time. When another update or dashboard is already updating the same tracked repo or git-installed skill, the update waits for it to finish. After a minute it gives up with another skillshare process is still updating <path>.
Example Output
$ skillshare update --all
✓ Audit 3 skills, no findings
✓ Updated 4, 12 up to date, 1 skipped · 6.2s
Next
skillshare sync link the changes into your targets
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 declared in metadata but missing on disk
! _team-skills clone directory absent
Run 'skillshare install -g' to rehydrate tracked repositories, or 'skillshare uninstall <name> -g' to remove an unwanted declaration
This applies to both global and project (-p) mode. To recreate the clones from metadata, run no-argument install (see Rehydrating After a Fresh Clone).
In global mode, you can instead run skillshare uninstall <name> -g to remove an unwanted declaration without a checkout; nothing moves to trash and there is no trash undo. Project mode suggests skillshare install -p and does not support declaration-only removal.
Stale Skill Cleanup (--prune)
When an upstream repository renames or removes a skill, update detects it as stale and warns you:
Deleted upstream
! frontend/old-skill stale — no longer in the upstream repository
Run with --prune to remove them
Add --prune to automatically remove stale skills (moved to trash, not permanently deleted):
skillshare update --all --prune
check also reports stale skills:
skillshare check --all
# ! old-skill stale — no longer in the upstream repository
:::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
Before publishing tracked updates, update audits an isolated candidate. The active checkout and existing target links keep serving the old content until approval:
- Tracked repos (
git pull) pull and scan in a private checkout at the active threshold (audit.block_threshold, defaultCRITICAL), then publish the exact audited commit without another upstream pull - 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? Yes No
- Yes — Accept the update despite findings
- No (default) — Discard the candidate; the active checkout stays unchanged
Non-Interactive Mode (CI/CD)
In non-interactive environments, blocking findings reject the candidate and the command exits with a non-zero code. Scan errors also leave the active checkout and metadata unchanged, even with --force. Publication is not an atomic multi-file switch.
# Bypass the audit gate when you trust the source
skillshare update --all --skip-audit
:::caution
--skip-audit disables the security scan entirely. Use it only when you trust the source or have an external audit process.
:::
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. Force Retry on the dashboard's Updates tab records them the same way, and both honor findings accepted from either one. skillshare audit --respect-accepted and the dashboard's Audit page honor them too; see audit — Accepted findings.
1 previously accepted finding skipped
Acceptance keys ignore line numbers and include the rule, file, matched text, and any detector-specific evidence. For whitespace-padding, changed padded content produces a new key; density findings use all eligible file content as evidence. New findings or changed evidence block 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:
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:
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:
# 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.
A skill installed from a repository is protected the same way. When its files no longer match the ones recorded at install time, update skips it and reports local changes since install; skillshare check lists it as modified, and skillshare check <name> --diff shows what you changed. Copy your edits elsewhere if you want to keep them, then discard them:
skillshare update my-skill --force
On the dashboard's Updates tab, the skill shows Modified locally and a View changes button that opens its changes on the skill's page; tick Force overwrite local edits before updating it, or use Force Retry on the skipped row. Updating it from the skill's own page shows the changes and asks before discarding them. update <name> --dry-run reports the skill as one it would skip. A modified skill that was also deleted upstream is kept until you add --force, even with --prune.
After Updating
Run skillshare sync to distribute changes to all targets:
skillshare update --all --diff # Update with file-level change summary
skillshare sync
Project Mode
Update skills and tracked repos in the project:
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 |
_-prefixed folder with a .git/ directory |
| Remote skill (with metadata) | Reinstall from source when upstream changed | Listed in .metadata.json |
| Local-path install | Re-copy from the recorded path | Listed in .metadata.json with type: local |
| Local skill | Skipped | Not listed in .metadata.json |
The _ prefix is optional, on the last path segment too — skillshare update team-skills -p auto-detects _team-skills, and skillshare update devops/team-skills -p finds a repo installed with --into devops at devops/_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.
Handling Conflicts
Tracked repos with uncommitted changes are blocked by default:
# 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
skillshare update --all -p
skillshare sync
git add .skillshare/ && git commit -m "Update remote skills"
See Also
- install — Install skills
- upgrade — Upgrade CLI and built-in skill
- sync — Sync to targets
- Project Skills — Project mode concepts