feat(skill): improve built-in skill for v0.16.12

- Expand description from 160 to 708 chars with broader trigger keywords
  (targets, backup/restore, trash, hub, symlink/copy, include/exclude filters)
- Add Skill Hubs recipe section (hub add/list/remove/default/index)
- Add Scripting & CI/CD recipe section (12 --json commands)
- Add --json column to Quick Lookup table
- Fix backup row: correctly show ✗ for project mode (global-only)
- Split tui/ui rows: tui/upgrade are ✗, ui supports -p
- Add hub to command list
- Update AI Caller Rules: hardcoded secret detection, --no-tui commands,
  12 --json commands
- Add --json flag docs to reference files (install, update, uninstall,
  status, diff, sync, collect)

Eval results: 100% pass rate across 5 test cases (up from 80% in iteration 1).
Key fix: Quick Lookup backup ✗ resolved false project-mode claims.
This commit is contained in:
Willie
2026-03-06 02:15:36 +08:00
parent f03ba456c0
commit 18bfe5ff96
4 changed files with 55 additions and 15 deletions
+46 -15
View File
@@ -1,11 +1,17 @@
---
name: skillshare
version: v0.16.11
version: v0.16.12
description: |
Syncs skills across AI CLI tools from a single source of truth.
Global (~/.config/skillshare/) or project (.skillshare/) mode.
Install from any Git host. Use when: "skillshare" CLI, skill management, or troubleshooting.
argument-hint: "[command] [target] [--dry-run] [-p|-g]"
Manages and syncs AI CLI skills across 50+ tools from a single source.
Use this skill whenever the user mentions "skillshare", runs skillshare commands,
manages skills (install, update, uninstall, sync, audit, check, diff, search),
or troubleshoots skill configuration (orphaned symlinks, broken targets, sync
issues). Covers both global (~/.config/skillshare/) and project (.skillshare/)
modes. Also use when: adding new AI tool targets (Claude, Cursor, Windsurf, etc.),
setting target include/exclude filters or copy vs symlink mode, using backup/restore
or trash recovery, piping skillshare output to scripts (--json), setting up CI/CD
audit pipelines, or building/sharing skill hubs (hub index, hub add).
argument-hint: "[command] [target] [--json] [--dry-run] [-p|-g]"
---
# Skillshare CLI
@@ -56,6 +62,15 @@ skillshare install github.com/team/repo --track -p # Track shared repo
skillshare push # Cross-machine: push on A
skillshare pull # Cross-machine: pull on B
```
### Skill Hubs
```bash
skillshare hub add https://example.com/hub.json # Save a hub source
skillshare hub add https://example.com/hub.json --label my-hub # With custom label
skillshare hub list # List saved hubs
skillshare hub default my-hub # Set default hub
skillshare hub remove my-hub # Remove a hub
skillshare hub index --source ~/.config/skillshare/skills/ --full --audit # Build hub index
```
### Controlling Where Skills Go
```bash
# SKILL.md frontmatter: targets: [claude] → only syncs to Claude
@@ -71,6 +86,21 @@ skillshare update my-skill && skillshare sync # Update one
skillshare update --all && skillshare sync # Update all
skillshare update --all --diff # Show what changed
```
### Scripting & CI/CD
```bash
skillshare status --json # Full status as JSON
skillshare check --json # Update status as JSON
skillshare sync --json # Sync results as JSON
skillshare diff --json # Diff results as JSON
skillshare install user/repo --json # Install result as JSON (implies --force --all)
skillshare update --all --json # Update results as JSON
skillshare uninstall my-skill --json # Uninstall result as JSON (implies --force)
skillshare collect claude --json # Collect result as JSON (implies --force)
skillshare target list --json # Target list as JSON
skillshare list --json # Skill list as JSON
skillshare search react --json # Search results as JSON
skillshare audit --format json # Audit results as JSON
```
### Recovery & Troubleshooting
```bash
skillshare trash restore <name> && skillshare sync # Undo delete
@@ -82,21 +112,22 @@ skillshare install user/repo --skip-audit # Bypass scan entirely
See [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) for more.
## Quick Lookup
| Commands | Project? |
|----------|:--------:|
| `status`, `diff`, `list`, `doctor` | ✓ (auto) |
| `sync`, `collect` | ✓ (auto) |
| `install`, `uninstall`, `update`, `check`, `search`, `new` | ✓ (`-p`) |
| `target`, `audit`, `trash`, `log` | ✓ (`-p`) |
| `push`, `pull`, `backup`, `restore` | ✗ |
| `tui`, `ui`, `upgrade` | ✓ |
| Commands | Project? | `--json`? |
|----------|:--------:|:---------:|
| `status`, `diff`, `list`, `doctor` | ✓ (auto) | ✓ (except doctor) |
| `sync`, `collect` | ✓ (auto) | ✓ |
| `install`, `uninstall`, `update`, `check`, `search`, `new` | ✓ (`-p`) | ✓ (except new) |
| `target`, `audit`, `trash`, `log`, `hub` | ✓ (`-p`) | ✓ (target list, audit, log) |
| `push`, `pull`, `backup`, `restore` | ✗ | ✗ |
| `tui`, `upgrade` | ✗ | ✗ |
| `ui` | ✓ (`-p`) | ✗ |
## AI Caller Rules
1. **Non-interactive** — AI cannot answer prompts. Use `--force`, `--all`, `-s`, `--targets`, `--no-copy`, `--all-targets`, `--yes`.
2. **Sync after mutations** — `install`, `uninstall`, `update`, `collect`, `target` all need `sync`.
3. **Audit** — `install` auto-scans; CRITICAL blocks. `--force` to override, `--skip-audit` to bypass.
3. **Audit** — `install` auto-scans; CRITICAL blocks. `--force` to override, `--skip-audit` to bypass. Detects hardcoded secrets (API keys, tokens, private keys).
4. **Uninstall safely** — moves to trash (7 days). `trash restore <name>` to undo. **NEVER** `rm -rf` symlinks.
5. **Output** — `--json` for structured data, `--no-tui` for plain text, `tui off` to disable TUI globally, `--dry-run` to preview.
5. **Output** — `--json` for structured data (12 commands support it, see Quick Lookup). `--no-tui` for plain text on TUI commands (`list`, `log`, `audit`, `diff`, `trash list`, `backup list`). `tui off` disables TUI globally. `--dry-run` to preview.
## References
| Topic | File |
+5
View File
@@ -73,6 +73,7 @@ skillshare install user/repo --skip-audit # Skip security scan
| `--exclude <name>` | Skip specific skills during multi-skill install (repeatable) |
| `--skip-audit` | Skip security audit for this install |
| `--audit-threshold <t>` / `--threshold <t>` / `-T <t>` | Override block threshold for this run (`critical\|high\|medium\|low\|info`; shorthand: `c\|h\|m\|l\|i`, plus `crit`, `med`) |
| `--json` | JSON output (implies `--force` + `--all`, non-interactive) |
| `--dry-run, -n` | Preview |
**Fuzzy subdirectory resolution:** When a monorepo has nested skill directories, you can specify just the skill name — e.g., `user/repo/vue-best-practices` finds `skills/vue-best-practices/` automatically. Fails with an error if multiple matches exist.
@@ -142,6 +143,7 @@ skillshare update _repo --force -p # Discard local changes
| `--force, -f` | Discard local changes and force update |
| `--dry-run, -n` | Preview without making changes |
| `--skip-audit` | Skip post-update security audit gate |
| `--json` | JSON output |
| `--diff` | Show file-level change summary after update |
**Safety:** Tracked repos with uncommitted changes are skipped. Use `--force` to override.
@@ -173,6 +175,9 @@ skillshare uninstall -G frontend -p --force
# Preview
skillshare uninstall --group frontend --dry-run
# JSON output (implies --force)
skillshare uninstall my-skill --json
```
**Group auto-detection:** When uninstalling a directory that contains sub-skills, the confirmation prompt shows `Uninstalling group (N skills)` with a list of contained skills.
+2
View File
@@ -9,6 +9,7 @@ Overview of source, targets, and sync state.
```bash
skillshare status # Auto-detects mode
skillshare status -g # Force global
skillshare status --json # JSON output (global mode only)
```
Project mode output includes: source path, targets with sync mode, remote skills list.
@@ -25,6 +26,7 @@ skillshare diff claude # Specific target
skillshare diff --stat # File-level changes (plain text)
skillshare diff --patch # Full unified diff (plain text)
skillshare diff --no-tui # Plain text, skip TUI
skillshare diff --json # JSON output (implies --no-tui)
skillshare diff -p # Project mode
skillshare diff -g # Force global
```
+2
View File
@@ -18,6 +18,7 @@ skillshare sync # Execute (auto-detects mode)
skillshare sync --all # Sync skills + extras
skillshare sync --dry-run # Preview
skillshare sync --force # Override conflicts
skillshare sync --json # JSON output
skillshare sync -g # Force global mode
```
@@ -62,6 +63,7 @@ Import skills from target(s) to source.
skillshare collect claude # From specific target
skillshare collect --all # From all targets
skillshare collect --dry-run # Preview
skillshare collect claude --json # JSON output (implies --force)
# Project (auto-detected or -p)
skillshare collect claude # From project target