mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 12:23:22 +00:00
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
400 lines
12 KiB
Markdown
400 lines
12 KiB
Markdown
---
|
||
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
|
||
|
||

|
||
|
||
## 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 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|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.
|
||
|
||
### 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
|
||
```
|
||
|
||
## 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
|
||
|
||
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.
|
||
:::
|
||
|
||
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
|
||
```
|
||
|
||
## 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`.
|
||
|
||
### 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
|
||
```
|
||
|
||
### 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
|