From bf1a12545fcc8f35c6fc172dfed1063e980ec00d Mon Sep 17 00:00:00 2001 From: Willie Date: Wed, 11 Feb 2026 21:42:51 +0800 Subject: [PATCH] docs: update built-in skill references to v0.11.7 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Catch up skill references with features added in v0.11.4–0.11.7: - SKILL.md: bump version, add init-rules command, inline ui -g/-p hint - init.md: add --skill/--no-skill flags, update non-interactive examples - install.md: add --into and --skip-audit flags with examples - audit.md: rewrite with --threshold, --json, --init-rules, path scanning, LOW/INFO severity, custom rules (three-layer merge), risk scoring - targets.md: note 46+ built-in targets - status.md: note upgrade --skill is opt-in - TROUBLESHOOTING.md: add audit rules and nested skill tips - Remove ui.md — AI only needs ui -g/-p from command table --- skills/skillshare/SKILL.md | 9 +- .../skillshare/references/TROUBLESHOOTING.md | 2 + skills/skillshare/references/audit.md | 113 +++++++++++++++--- skills/skillshare/references/init.md | 6 +- skills/skillshare/references/install.md | 9 +- skills/skillshare/references/status.md | 2 + skills/skillshare/references/targets.md | 2 +- skills/skillshare/references/ui.md | 96 --------------- 8 files changed, 118 insertions(+), 121 deletions(-) delete mode 100644 skills/skillshare/references/ui.md diff --git a/skills/skillshare/SKILL.md b/skills/skillshare/SKILL.md index 8dccef237..91a4bf333 100644 --- a/skills/skillshare/SKILL.md +++ b/skills/skillshare/SKILL.md @@ -1,11 +1,11 @@ --- name: skillshare -version: 0.11.0 +version: 0.11.7 description: | Syncs skills across AI CLI tools (Claude, Cursor, Windsurf, etc.) from a single source of truth. Global mode (~/.config/skillshare/) and project mode (.skillshare/ per-repo). Commands: status, sync, install, uninstall, update, check, search, new, collect, - push, pull, diff, list, doctor, audit, trash, log, backup, restore, target, ui, upgrade. + push, pull, diff, list, doctor, audit, init-rules, trash, log, backup, restore, target, ui, upgrade. Use when: managing skills across AI tools, "skillshare" CLI, skill sync/install/search, project skills setup, security audit, web dashboard, or troubleshooting. argument-hint: "[command] [target] [--dry-run] [-p|-g]" @@ -36,7 +36,7 @@ Force with `-p` (project) or `-g` (global). | **Trash** | `trash list\|restore\|delete\|empty` | ✓ (`-p`) | | **Log** | `log [--audit] [--tail N]` | ✓ (`-p`) | | **Backup** | `backup`, `restore` | ✗ | -| **Web UI** | `ui` | ✓ (`-p`) | +| **Web UI** | `ui` (`-g` global, `-p` project) | ✓ (`-p`) | | **Upgrade** | `upgrade [--cli\|--skill]` | — | **Workflow:** Most commands require `sync` afterward to distribute changes. @@ -49,7 +49,7 @@ AI cannot respond to CLI prompts. Always pass flags to skip interactive prompts. ```bash # Key non-interactive patterns -skillshare init --no-copy --all-targets --git # Global fresh start +skillshare init --no-copy --all-targets --git --skill # Global fresh start skillshare init -p --targets "claude-code,cursor" # Project init skillshare install user/repo --all # Install all skills skillshare install user/repo -s pdf,commit # Select specific @@ -78,5 +78,4 @@ See [audit.md](references/audit.md) and [trash.md](references/trash.md) for deta | 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) | | Troubleshooting | [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) | diff --git a/skills/skillshare/references/TROUBLESHOOTING.md b/skills/skillshare/references/TROUBLESHOOTING.md index 27d4d0c38..cc8fbe695 100644 --- a/skills/skillshare/references/TROUBLESHOOTING.md +++ b/skills/skillshare/references/TROUBLESHOOTING.md @@ -15,6 +15,8 @@ | 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 | +| Custom audit rules not applying | Verify `audit-rules.yaml` path: global (`~/.config/skillshare/`) or project (`.skillshare/`). Run `skillshare audit --init-rules` to create template | +| Nested skill not found | `update`/`uninstall` resolve short names — e.g., `skillshare update vue` finds `frontend/vue/vue-best-practices`. Use full path if ambiguous | ## Diagnostic Commands diff --git a/skills/skillshare/references/audit.md b/skills/skillshare/references/audit.md index 348a28eb3..55e42ef0d 100644 --- a/skills/skillshare/references/audit.md +++ b/skills/skillshare/references/audit.md @@ -7,50 +7,131 @@ Scan skills for prompt injection, data exfiltration, credential access, destruct ```bash skillshare audit # Scan all skills skillshare audit # Scan specific skill +skillshare audit # Scan file or directory path skillshare audit -p # Scan project skills ``` +## Flags + +| Flag | Description | +|------|-------------| +| `-p, --project` | Scan project-level skills | +| `-g, --global` | Scan global skills | +| `--threshold ` | Block threshold override: `critical\|high\|medium\|low\|info` | +| `--json` | Machine-readable JSON output with risk scores | +| `--init-rules` | Create a starter `audit-rules.yaml` | +| `-h, --help` | Show help | + ## Severity Levels -| Level | Meaning | Install behavior | -|-------|---------|-----------------| +| Level | Meaning | Default install behavior | +|-------|---------|--------------------------| | **CRITICAL** | Prompt injection, data exfil, credential theft | **Blocked** (use `--force` to override) | | **HIGH** | Destructive commands, hidden unicode, obfuscation | Warning shown | | **MEDIUM** | Suspicious URLs, system path writes | Warning shown | +| **LOW** | Minor concerns, uncommon patterns | Warning shown | +| **INFO** | Informational observations | Warning shown | + +## Configurable Block Threshold + +The default threshold is `CRITICAL` — only CRITICAL findings block `install`. Override per-command or globally: + +```bash +# Per-command override +skillshare audit --threshold high # Block on HIGH+ findings + +# Global config (config.yaml) +audit: + block_threshold: HIGH # Block on HIGH+ for all installs +``` ## 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. +- **Findings at/above threshold → install blocked.** User must `--force` to proceed. +- **Findings below threshold → warning displayed** after successful install. +- **`--skip-audit`** skips security scanning entirely for a single install. +- Web UI shows a confirm dialog on blocked findings with "Force Install" option. ```bash -skillshare install user/repo # Auto-audit, block on CRITICAL -skillshare install user/repo --force # Override CRITICAL block +skillshare install user/repo # Auto-audit, block on threshold +skillshare install user/repo --force # Override block +skillshare install user/repo --skip-audit # Skip audit entirely ``` ## Output -Per-skill results with tree-style findings: +Per-skill results with risk scoring: ``` -[1/5] ✓ my-skill (12ms) -[2/5] ! risky-skill (8ms) - ├─ MEDIUM: URL used in command context (scripts/run.sh:14) - └─ HIGH: base64 decode pipe may hide malicious content (SKILL.md:42) -[3/5] ✗ bad-skill (5ms) - └─ CRITICAL: prompt injection attempt (SKILL.md:3) +[1/5] ✓ my-skill 0.1s +[2/5] ! risky-skill 0.1s (MODERATE 35/100) +[3/5] ✗ bad-skill 0.1s (SEVERE 85/100) +``` + +Single-skill scan shows detailed findings: + +``` + MEDIUM: URL used in command context (scripts/run.sh:14) + HIGH: base64 decode pipe may hide malicious content (SKILL.md:42) + Risk: MODERATE (35/100) ``` Summary box: ``` -Scanned: 5 | Passed: 3 | Warning: 1 | Failed: 1 +┌─ Summary ───────────────────────┐ +│ Threshold: CRITICAL │ +│ Scanned: 5 skill(s) │ +│ Passed: 3 │ +│ Warning: 1 │ +│ Failed: 1 │ +│ Severity: c/h/m/l/i = 1/1/1/0/0 │ +│ Risk: SEVERE (85/100) │ +└─────────────────────────────────┘ ``` -`Failed` only counts skills that contain at least one `CRITICAL` finding. `HIGH` and `MEDIUM` findings are grouped into `Warning`. +`Failed` counts skills with findings at/above the threshold. `Warning` counts skills with findings below the threshold. + +## Custom Audit Rules + +Create custom rules to extend or override built-in patterns. + +### Init + +```bash +skillshare audit --init-rules # Global: ~/.config/skillshare/audit-rules.yaml +skillshare audit --init-rules -p # Project: .skillshare/audit-rules.yaml +``` + +### Three-Layer Merge + +Rules merge in order (later overrides earlier): + +1. **Built-in** — shipped with skillshare binary +2. **Global** — `~/.config/skillshare/audit-rules.yaml` +3. **Project** — `.skillshare/audit-rules.yaml` (project mode only) + +### Rule Format + +```yaml +rules: + # Add a new rule + - id: flag-todo + severity: MEDIUM + pattern: todo-comment + message: "TODO comment found" + regex: '(?i)\bTODO\b' + + # Disable a built-in rule + - id: system-writes-0 + enabled: false + + # Override severity of a built-in rule + - id: destructive-commands-2 + severity: LOW +``` ## Logging diff --git a/skills/skillshare/references/init.md b/skills/skillshare/references/init.md index 70e0212bc..5fa9babd2 100644 --- a/skills/skillshare/references/init.md +++ b/skills/skillshare/references/init.md @@ -21,6 +21,8 @@ Initialize skillshare configuration (global or project). | `--discover --select "a,b"` | Non-interactive discovery | | `--source ` | Custom source path | | `--remote ` | Set git remote | +| `--skill` | Install built-in skillshare skill (opt-in) | +| `--no-skill` | Skip built-in skill installation | | `--dry-run` | Preview changes | ### AI Usage (Non-Interactive) @@ -30,10 +32,10 @@ Initialize skillshare configuration (global or project). ls ~/.claude/skills ~/.cursor/skills 2>/dev/null | head -10 # Step 2a: Fresh start -skillshare init --no-copy --all-targets --git +skillshare init --no-copy --all-targets --git --skill # Step 2b: Import existing skills -skillshare init --copy-from claude --all-targets --git +skillshare init --copy-from claude --all-targets --git --skill # Step 3: Verify skillshare status diff --git a/skills/skillshare/references/install.md b/skills/skillshare/references/install.md index 35c3baf38..002560f47 100644 --- a/skills/skillshare/references/install.md +++ b/skills/skillshare/references/install.md @@ -43,11 +43,16 @@ skillshare install anthropics/skills/skills/pdf -p # Install to .skillshare/s skillshare install github.com/team/repo --track -p # Track in project skillshare install -p # Install all remote skills from config +# Organize into subdirectories +skillshare install anthropics/skills --into frontend # → skills/frontend/ +skillshare install user/repo --into tools -p # → .skillshare/skills/tools/ + # Selective install (non-interactive) skillshare install anthropics/skills -s pdf,commit # Specific skills skillshare install anthropics/skills --all # All skills skillshare install anthropics/skills -y # Auto-accept skillshare install anthropics/skills -s pdf -p # Selective + project mode +skillshare install user/repo --skip-audit # Skip security scan ``` ### Flags @@ -60,15 +65,17 @@ skillshare install anthropics/skills -s pdf -p # Selective + project mode | `--update, -u` | Update if exists | | `--track, -t` | Track for updates (preserves .git) | | `--skill, -s ` | Select specific skills from multi-skill repo (comma-separated) | +| `--into ` | Install into subdirectory (e.g., `--into frontend`) | | `--all` | Install all discovered skills without prompting | | `--yes, -y` | Auto-accept all prompts (CI/CD friendly) | +| `--skip-audit` | Skip security audit for this install | | `--dry-run, -n` | Preview | **Tracked repos:** Prefixed with `_`, nested with `__` (e.g., `_team__frontend__ui`). **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. +**Security audit:** Install auto-scans skills after download. CRITICAL findings block install — use `--force` to override, `--skip-audit` to skip entirely. HIGH/MEDIUM shown as warnings. **After install:** `skillshare sync` diff --git a/skills/skillshare/references/status.md b/skills/skillshare/references/status.md index 71245fc21..a2dca9a1b 100644 --- a/skills/skillshare/references/status.md +++ b/skills/skillshare/references/status.md @@ -75,4 +75,6 @@ skillshare upgrade --force # Skip confirmation skillshare upgrade --dry-run # Preview ``` +**Note:** `upgrade --skill` is opt-in — it won't auto-install the built-in skill if it's not already present. Use `init --skill` or `upgrade --skill` to install it explicitly. + **After upgrading skill:** `skillshare sync` diff --git a/skills/skillshare/references/targets.md b/skills/skillshare/references/targets.md index c4977580a..2805f33c3 100644 --- a/skills/skillshare/references/targets.md +++ b/skills/skillshare/references/targets.md @@ -1,6 +1,6 @@ # Target Management -Manage AI CLI tool targets (Claude, Cursor, Windsurf, etc.). +Manage AI CLI tool targets (Claude, Cursor, Windsurf, etc.). Skillshare supports 46+ built-in targets. ## Global Targets diff --git a/skills/skillshare/references/ui.md b/skills/skillshare/references/ui.md deleted file mode 100644 index 1a73409c5..000000000 --- a/skills/skillshare/references/ui.md +++ /dev/null @@ -1,96 +0,0 @@ -# Web Dashboard (`skillshare ui`) - -Launch a browser-based dashboard for visual skill management. Single binary — no extra setup. - -## Usage - -```bash -skillshare ui # Global mode (auto-opens browser) -skillshare ui -p # Project mode -skillshare ui -g # Force global mode -``` - -Auto-detects project mode when `.skillshare/config.yaml` exists in cwd. - -## Flags - -| Flag | Default | Description | -|------|---------|-------------| -| `-p, --project` | | Project mode (`.skillshare/`) | -| `-g, --global` | | Global mode (`~/.config/skillshare/`) | -| `--port ` | `19420` | HTTP server port | -| `--host ` | `127.0.0.1` | Bind address (`0.0.0.0` for Docker/remote) | -| `--no-open` | `false` | Don't open browser automatically | - -## Dashboard Pages - -| Page | Description | -|------|-------------| -| **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 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 | -| **Config** | YAML config editor with validation | - -## Project Mode Differences - -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 - -All endpoints at `/api/`, returning JSON: - -```bash -# Examples -curl http://127.0.0.1:19420/api/overview -curl http://127.0.0.1:19420/api/skills -curl -X POST http://127.0.0.1:19420/api/sync -d '{"dryRun":true}' -``` - -| Method | Path | Description | -|--------|------|-------------| -| GET | `/api/overview` | Skill/target counts, mode, version | -| GET | `/api/skills` | List all skills with metadata | -| GET | `/api/skills/{name}` | Skill detail + SKILL.md content | -| DELETE | `/api/skills/{name}` | Uninstall a skill | -| GET | `/api/targets` | List targets with status | -| POST | `/api/targets` | Add a target | -| DELETE | `/api/targets/{name}` | Remove a target | -| POST | `/api/sync` | Run sync (`dryRun`, `force`) | -| 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 | - -## Docker / Remote - -```bash -skillshare ui --host 0.0.0.0 --no-open # Global -skillshare ui -p --host 0.0.0.0 --no-open # Project -``` - -Access from host: `http://localhost:19420`