Skillshare CLI
Global: ~/.config/skillshare/skills/ → all AI CLIs. Project: .skillshare/skills/ → repo-local.
Auto-detects project mode from .skillshare/config.yaml or skillshare/config.yaml (hidden wins when both exist). Force with -p or -g.
Recipes
Getting Started
bashskillshare init --no-copy --all-targets --git --skill # Fresh global setup skillshare init -p --targets "claude,cursor" # Fresh project setup skillshare init -p --visible # Use skillshare/ instead of .skillshare/ skillshare init --copy-from claude --all-targets --git # Import from existing CLI skillshare init --discover --select "windsurf" # Add new AI tool later
Installing Skills
bashskillshare install user/repo -s pdf,commit # Select specific skills skillshare install user/repo --all # Install everything skillshare install user/repo --into frontend # Place in subdirectory skillshare install gitlab.com/team/repo # Any Git host skillshare install user/repo --track # Enable `update` later skillshare install user/repo -b develop --all # Install from branch skillshare install user/repo --track -b develop # Track specific branch skillshare install user/repo -s pdf -p # Install to project skillshare install # Rehydrate remote skills/tracked repos skillshare sync # Always sync after install
Extras (Rules, Commands, Prompts)
bashskillshare extras init rules --target ~/.claude/rules --target ~/.cursor/rules skillshare extras init commands --target ~/.claude/commands --mode copy skillshare extras init rules --target ~/.claude/rules --source ~/shared/rules # custom source (global only) skillshare extras init rules --target ~/.cursor/rules --force # overwrite existing skillshare extras init # Interactive TUI wizard (incl. source step) skillshare extras source # Show current extras_source skillshare extras source ~/shared/extras # Set global extras_source skillshare extras list # Show status per target skillshare extras list --json # JSON with source_type field skillshare extras collect rules # Pull local files into source skillshare extras remove rules # Remove from config (source preserved) skillshare extras init agents --target ~/.claude/agents --flatten # Flatten subdirs into root skillshare extras rules --mode copy # Change sync mode of a target skillshare extras agents --flatten # Enable flatten on existing target skillshare extras rules --add-target ~/.cursor/rules # Add a target to an existing extra skillshare extras rules --remove-target ~/.cursor/rules --prune # Remove a target (--prune deletes synced files) skillshare sync extras # Sync all extras to targets skillshare sync extras --dry-run --force # Preview / overwrite conflicts skillshare sync --all # Sync skills + extras together
Project extras always read from <sources.extras>/<name> (default .skillshare/extras/<name>); per-extra source and extras source are global-only. For project agents, prefer target agents: unless you need extras-only flatten/extension.
A target can set an extension: field in config.yaml to transform each source file during sync (e.g. markdown → TOML for Gemini/Codex); implies copy mode. See extras.md for details.
Extensions (Content Transformation)
bash# Extension is a directory at .skillshare/extensions/<name>/ # extension.yaml controls: run command, output_ext, description # Official extensions: https://github.com/runkids/skillshare/tree/main/extensions
extension.yaml format:
yamlrun: ["node", "convert.js"] # or ["python3", "convert.py"] etc. output_ext: toml # renames output file extension description: "MD → Codex TOML"
Add extension to an extras target in config.yaml:
yamlextras: - name: agents targets: - path: .claude/agents # plain copy/merge - path: .codex/agents extension: codex-agents # transform + rename to .toml
Caveats:
extension:is only supported on extras targets — native agents targets ignore it- Implies
copymode; merge/symlink won't apply - Claude Code sets NODE_OPTIONS that break node extensions — use
env -u NODE_OPTIONS node convert.jsin run - Files missing required frontmatter fields fail validation and are skipped
Creating & Discovering Skills
bashskillshare new my-skill # Create with interactive pattern selection skillshare new my-skill -P reviewer # Use reviewer pattern directly skillshare search "react testing" # Search GitHub for skills skillshare collect # Pull target-local changes back to source
Removing Skills
bashskillshare uninstall my-skill # Remove one (moves to trash) skillshare uninstall skill-a skill-b # Remove multiple skillshare uninstall -G frontend # Remove entire group skillshare sync # Always sync after uninstall
Enable / Disable Skills
bashskillshare disable draft-* # Hide from sync (adds to .skillignore) skillshare enable draft-* # Restore (removes from .skillignore) skillshare disable my-skill -p # Project mode skillshare disable my-skill --dry-run # Preview # TUI: press E in `skillshare list` to toggle skillshare sync # Always sync after toggle
Team / Organization
bash# Creator: init project (see Getting Started) → add skills → commit .skillshare/ skillshare install -p && skillshare sync # Member: clone → install → sync skillshare install github.com/team/repo --track -p # Track shared repo skillshare commit -m "Update skill" # Local checkpoint, no push skillshare push # Cross-machine: push on A skillshare pull # Cross-machine: pull on B
Skill Hubs
bashskillshare 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 add git@ghe.corp.com:team/skills.git --label ghe # SSH/private/GHE hub source 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: metadata.targets: [claude] → only syncs to Claude skillshare target claude --add-include "team-*" # glob filter skillshare target claude --add-agent-include "team-*" # agent glob filter skillshare target claude --add-exclude "_legacy*" # exclude pattern skillshare target claude --agent-mode copy # agents copy mode skillshare target codex --mode copy && skillshare sync --force # copy mode # .skillignore — hide skills/dirs from discovery (gitignore syntax) # Root-level: <source>/.skillignore (affects all commands) # Repo-level: <source>/_repo/.skillignore (scoped to that repo) # .skillignore.local — local override (not committed), negation overrides base
See targets.md for details.
Updates & Maintenance
bashskillshare check # See what has updates 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
bashskillshare 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 # Global JSON; dirty tracked repos still require --force skillshare collect claude --json # Collect result as JSON; existing items still require --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 skillshare doctor --json # Health check as JSON (exit 1 on errors)
Recovery & Troubleshooting
bashskillshare trash restore <name> && skillshare sync # Undo delete skillshare sync # Skill missing? Re-sync skillshare doctor && skillshare status # Diagnose issues skillshare install user/repo --force # Override audit block skillshare install user/repo --skip-audit # Bypass scan entirely
See TROUBLESHOOTING.md for more.
Quick Lookup
| Commands | Project? | --json? |
|---|---|---|
status, diff, list, doctor | ✓ (auto) | ✓ |
sync, collect | ✓ (auto) | ✓ |
install, uninstall, update, check, search, new | ✓ (-p) | ✓ (except new) |
target, audit, analyze, trash, log, hub | ✓ (-p) | ✓ (target list, audit, analyze, log) |
extras init/list/remove/collect/source (+ --mode/--add-target/--remove-target flags on extras <name>) | ✓ (-p, except source) | ✓ (list, mode, targets) |
enable, disable | ✓ (auto) | ✗ |
commit, push, pull, backup, restore | ✗ | ✗ |
tui, upgrade | ✗ | ✗ |
ui | ✓ (-p) | ✗ |
AI Caller Rules
- Non-interactive — AI cannot answer prompts. Use
--force,--all,-s,--targets,--no-copy,--all-targets,--yes. - Sync after mutations —
install,uninstall,update,collect,targetall needsync. - Audit —
installauto-scans; CRITICAL blocks.--forceto override,--skip-auditto bypass. Detects hardcoded secrets (API keys, tokens, private keys). - Uninstall safely — moves to trash (7 days).
trash restore <name>to undo. NEVERrm -rfsymlinks. - Output —
--jsonfor structured data (12 commands support it, see Quick Lookup).--no-tuifor plain text on TUI commands (list,log,audit,analyze,diff,trash list,backup list,target list).tui offdisables TUI globally.--dry-runto preview. - Node extensions in Claude Code —
NODE_OPTIONSis preloaded by the Claude Code harness and causes node to crash when running extensions. Always userun: ["env", "-u", "NODE_OPTIONS", "node", "convert.js"]inextension.yamlwhen writing extensions that use Node.js.
References
| Topic | File |
|---|---|
| Init flags | init.md |
| Sync/collect/commit/push/pull | sync.md |
| Install/update/uninstall/new | install.md |
| Status/diff/list/search/check | status.md |
| Security audit | audit.md |
| Trash | trash.md |
| Operation log | log.md |
| Targets | targets.md |
| Extras (rules/commands/prompts) | extras.md |
| Backup/restore | backup.md |
| Troubleshooting | TROUBLESHOOTING.md |
