docs: update built-in skill references to v0.11.7

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
This commit is contained in:
Willie
2026-02-13 14:21:37 +08:00
parent d8699762ad
commit bf1a12545f
8 changed files with 118 additions and 121 deletions
+4 -5
View File
@@ -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) |
@@ -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
+97 -16
View File
@@ -7,50 +7,131 @@ Scan skills for prompt injection, data exfiltration, credential access, destruct
```bash
skillshare audit # Scan all skills
skillshare audit <name> # Scan specific skill
skillshare audit <path> # 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 <t>` | 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
+4 -2
View File
@@ -21,6 +21,8 @@ Initialize skillshare configuration (global or project).
| `--discover --select "a,b"` | Non-interactive discovery |
| `--source <path>` | Custom source path |
| `--remote <url>` | 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
+8 -1
View File
@@ -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 <names>` | Select specific skills from multi-skill repo (comma-separated) |
| `--into <dir>` | 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`
+2
View File
@@ -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`
+1 -1
View File
@@ -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
-96
View File
@@ -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 <port>` | `19420` | HTTP server port |
| `--host <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`