Skill Sharing

Skill Sharing

Share skills, rules, commands, and agents across machines and teams using Skillshare (v0.17+) and a Git repository.

Two Modes

Skills in the source are synced to the target (~/.claude/skills/) where Claude uses them.

Sharing Tiers

Primary Interface

Use the Share page in the Pilot Shell Console dashboard (http://localhost:41777/#/share):

• Source & Sync card — Project (first) and Global sections; Sync/Collect buttons appear when out of sync
• Remote Share card — configure git remotes, Push/Pull buttons for cross-machine sync
• Assets grid — merged view of all global + project skills with scope/type badges
• Install from URL — install skills globally or to a project
• How does this work? / CLI Reference — collapsed help sections

Extras — First-Class Resource Management (v0.17+)

Extras manage non-skill resources (rules, commands, agents, prompts) with their own CLI command group. Each extra has a name, a source directory, and one or more target directories.

Directory structure:

~/.config/skillshare/
├── skills/           ← skill source
└── extras/           ← extras source root (new in v0.17)
    ├── rules/        ← synced to ~/.claude/rules
    ├── commands/     ← synced to ~/.claude/commands
    └── agents/       ← synced to ~/.claude/agents

Core commands:

# Create a new extra (interactive wizard or CLI flags)
skillshare extras init rules --target ~/.claude/rules --target ~/.cursor/rules
skillshare extras init rules -p --target .claude/rules          # project-scoped

# List extras with sync status per target
skillshare extras list                                           # interactive TUI
skillshare extras list --json -g                                 # JSON output

# Change sync mode for a target
skillshare extras mode rules --mode copy                         # single-target shorthand
skillshare extras mode rules --target ~/.claude/rules --mode copy

# Collect files from a target back into source
skillshare extras collect rules --from ~/.claude/rules
skillshare extras collect rules --from ~/.claude/rules --dry-run

# Remove an extra (source files preserved)
skillshare extras remove rules

Sync modes:

Project-mode extras — extras now work at project level (-p), not just global:

skillshare extras init rules -p --target .claude/rules
skillshare sync -p --all                                         # sync skills + extras

Note: Pilot-managed rules/commands (installed by the Pilot installer) are tracked via manifest and should NOT be placed in extras. Extras are for user-created assets you want to share across machines.

Key Concepts

• Sync: Distributes assets from source to target. Must run after every mutation (install, uninstall, update, collect).
• Collect: Imports files from a target back into the source directory so they can be pushed/shared.
• Team Remote: Git remotes for global skills only. Project skills are shared by committing .skillshare/ to the project repo instead.
• Hub: Curated skill catalogs. skillshare hub add <url> to subscribe, skillshare hub index to build one.
• Audit: Security scan on install. skillshare audit --threshold high for CI.

Health Checks & Diagnostics

skillshare doctor --json provides machine-readable health checks for CI pipelines:

skillshare doctor                      # human-readable output
skillshare doctor --json               # structured JSON (CI-friendly)

# CI gate — fail if any errors
skillshare doctor --json | jq -e '.summary.errors == 0'

# Check .skillignore status
skillshare doctor --json | jq '.checks[] | select(.name == "skillignore")'

.skillignore — Hide Skills from Discovery

Place a .skillignore at the source root or inside a tracked repo to hide skills from all commands. Uses full gitignore syntax:

# ~/.config/skillshare/skills/.skillignore
draft-*          # hide all draft skills
_archived/       # hide entire directory
test-fixture     # hide specific skill

# Negation, character classes, recursive globs also work
!test-important  # keep this one despite draft-* match
**/temp          # ignore temp at any depth

Cross-Machine Sync and Organization Sharing

Personal remote — your skills across your machines:

skillshare init --remote git@github.com:you/my-skills.git  # first machine
skillshare push -m "Add skill"
# On another machine:
skillshare init --remote git@github.com:you/my-skills.git  # auto-pulls
skillshare pull

Tracked repos — team/org repos:

skillshare install github.com/my-team/team-skills --track --name team-skills
skillshare update --all && skillshare sync

Centralized skills repo (--config local) — one repo for skills, each developer manages own targets:

# Creator: set up the shared repo
skillshare init -p --config local --targets claude
git add .skillshare/ && git commit && git push

# Teammate: clone and configure own targets
git clone <repo> && cd <repo>
skillshare init -p                          # auto-detects shared repo mode
skillshare target add projB ~/DEV/projB/.cursor/skills -p
skillshare sync -p

Org sharing pattern (two-channel, used at scale):

Both channels read from the same repo — no lock-in, skills are plain markdown files.

Hub Index for org-wide discoverability:

cd ~/my-org/skills-directory
skillshare hub index --audit -o ./skillshare-hub.json
# Commit to repo — GitHub raw URL makes it searchable by anyone

Tool Portability in Skills

Skills are shared with users who may not have Pilot Shell. Only reference built-in Claude Code tools in skill content:

If a skill requires a non-standard tool, list it as a prerequisite.

/create-skill and /setup-rules Integration

/create-skill creates skills in .skillshare/skills/ if it exists in the project (runs skillshare sync -p afterward). Otherwise falls back to .claude/skills/.

/setup-rules focuses exclusively on rules and AGENTS.md — it does not create skills.

When to Use

Non-Interactive Usage (for Claude)

Claude cannot answer interactive prompts. Always use non-interactive flags:

CLI Quick Reference

# Skills — global
skillshare status -g && skillshare list -g
skillshare sync -g                            # sync skills only
skillshare sync -g --all                      # sync skills + extras
skillshare install <url> -g
skillshare collect -g && skillshare diff -g

# Skills — project
skillshare init -p
skillshare sync -p && skillshare sync -p --all
skillshare install <url> -p

# Extras (v0.17+)
skillshare extras init <name> --target <path> [-p|-g]
skillshare extras list [--json] [-p|-g]
skillshare extras mode <name> --mode merge|copy|symlink
skillshare extras collect <name> --from <path>
skillshare extras remove <name>

# Cross-machine sync (global only)
skillshare init --remote <url>
skillshare push -m "Add skill"
skillshare pull

# Health & discovery
skillshare doctor [--json]
skillshare audit [--threshold high]
skillshare hub add <url>
skillshare hub index --full

# Organization (Team/Trial)
skillshare install <url> --track              # tracked org repo
skillshare update --all                       # update all tracked repos
skillshare check                              # check for available updates
skillshare trash restore <name>               # recover deleted skill (7-day)

Documentation

• Quick Start
• Extras Reference
• Cross-Machine Sync
• Project Setup
• Organization Sharing
• Full Command Reference