/skillshare

name: skillshare
description: |
  Manages and syncs AI CLI skills and agents across 50+ tools from a single source.
  Use this skill whenever the user mentions "skillshare", runs skillshare commands,
  manages skills or agents (install, update, uninstall, sync, commit, audit, analyze, check, diff, search),
  or troubleshoots skill/agent 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, building/sharing skill hubs (hub index, hub add), or working with
  agents (single .md files synced to agent-capable targets like Claude, Cursor,
  Augment, OpenCode) via positional `agents` filter or `--kind agent`, plus
  `.agentignore` and `enable`/`disable` for per-agent toggles.
argument-hint: "[command] [target] [--json] [--dry-run] [-p|-g]"
metadata:
  version: v0.20.25

Skillshare CLI

Global: `~/.config/skillshare/skills/` → all AI CLIs. Project: `.skillshare/skills/` → repo-local. Auto-detects project mode when `.skillshare/config.yaml` exists. Force with `-p` or `-g`.

Recipes

Getting Started

skillshare init --no-copy --all-targets --git --skill  # Fresh global setup
skillshare init -p --targets "claude,cursor"            # Fresh project setup
skillshare init --copy-from claude --all-targets --git  # Import from existing CLI
skillshare init --discover --select "windsurf"          # Add new AI tool later

Installing Skills

skillshare 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)

skillshare 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](references/extras.md) for details.

Extensions (Content Transformation)

# 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:

run: ["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:

extras:
  - 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 `copy` mode; merge/symlink won't apply
• Claude Code sets NODE_OPTIONS that break node extensions — use `env -u NODE_OPTIONS node convert.js` in run
• Files missing required frontmatter fields fail validation and are skipped

Creating & Discovering Skills

skillshare 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 sk