mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
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:
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`
|
||||
|
||||
|
||||
@@ -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,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
|
||||
|
||||
|
||||
@@ -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`
|
||||
Reference in New Issue
Block a user