Extend install/update with agent-aware --json output and apply the same audit block-threshold gate skills already use. Install: - install --json: imply --force; imply --all only when neither --skill nor --agent is set (so explicit selectors still work) - project-mode install now routes through cmdInstallProjectParsed so --json suppresses UI and emits a pure-JSON payload - agent installs propagate SourceDir so metadata lands in the agents root, not the install subdir - validation error lists --agent / --kind / --branch explicitly Update agents: - update agents supports --force, --skip-audit, --audit-threshold - tracked agent repos + metadata-backed single-file agents now run the same audit gate as skills; blocks roll back from a temp stage - JSON output returns the final per-agent status (updated/skipped/failed/up_to_date/...) by merging check results with batch update outcomes Audit: - auditInstalledAgent shares one helper with auditInstalledSkill (scan + cleanup callbacks); single-file agent scans now use audit.ScanFile / ScanFileForProject instead of staging the file into a temp directory - UpdateAgentFromDiscovery stages to temp, audits, then renames atomically (rename already overwrites on POSIX) Refactors pulled in while reworking these paths: - extract jsonUISuppressor helper in json_output.go and use it from install/update/update_agents; collapses 4 copies of the suppress/restore closure dance and the per-error failJSON block - drop relPath plumbing from installAgentFromDiscoveryInternal now that ScanFile doesn't need a staged relative path - list.go render functions now use theme.ANSI() so NO_COLOR is respected in plain-text output Tests: - add TestInstallAgentFromDiscovery_HighFindingBlocked (unit) - add TestUpdate_Agents_HighFindingBlockedByThreshold (integration) - add TestInstall_Project_JSON_Agent_PureJSON, TestUpdate_Agents_JSON_ReportsFinalStatus - fix TestList_SKILLSHARE_THEME_Light / TestList_NO_COLOR to write a config before invoking list - fix TestTargetList_NoTUI_FallsBackToPlainText assertion to match the new structured Mode: merge output - fix TestDoctor_AllGood_PassesAll by pinning SKILLSHARE_THEME=dark so the no-TTY theme fallback warning doesn't fire - add list_tui_content_test.go covering light/dark glamour base - list detail pane now picks LightStyleConfig on light terminals Docs: - update install.md, update.md, understand/agents.md for the new flags, JSON shapes, and agents update workflow
12 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
What Happens
For Tracked Repositories
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
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 force update |
--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 |
--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.
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, and local.
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 skill(s)
:::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 (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
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):
skillshare update --all --prune
check also reports stale skills:
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
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, defaultCRITICAL) - 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 findingsN(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.
# 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.
:::
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
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 |
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.
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
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
