This document provides a high-level introduction to the skillshare system, explaining its purpose as a centralized skill management tool for AI CLI assistants. It covers the single-source-of-truth concept, dual-mode architecture (global/project), key features including security auditing, and how the major system components fit together. For detailed command usage, see CLI Commands Reference. For configuration details, see Configuration. For architectural internals, see Architecture and Internals.
skillshare is a CLI tool that manages AI assistant skills (prompt engineering artifacts) from a single source directory and synchronizes them to 50+ AI CLI tools (Claude, Cursor, Windsurf, Codex, etc.). It solves the problem of manually copying skills between different AI assistants by treating one directory as the authoritative source and distributing from there.
The system operates in two modes:
~/.config/skillshare/skills/.skillshare/skills/Traditional workflow problems:
skillshare's solution:
Source Directory (single truth)
~/.config/skillshare/skills/ (global)
or .skillshare/skills/ (project)
│
│ skillshare sync
│
┌─────────┼─────────┬──────────┬──────────┐
│ │ │ │ │
Claude Cursor Windsurf Codex (50+ more)
All AI assistants read from symlinks (or copies) pointing back to the source. Edit anywhere, the change propagates automatically (with symlinks) or via explicit sync (with copies).
Sources: README.md43-89 skills/skillshare/SKILL.md18-20
The following diagram shows how the major system components interact:
Key Components:
| Component | Purpose | Code Location |
|---|---|---|
| CLI Binary | Main entry point, command dispatch | cmd/skillshare/main.go46-111 |
| Command Router | Maps command names to handler functions | cmd/skillshare/main.go18-44 |
| Mode Detection | Auto-detects global vs project mode | Referenced in command files |
| Install System | Downloads, validates, and places skills | internal/install |
| Sync Engine | Distributes skills to targets using merge/copy/symlink modes | internal/sync |
| Audit Engine | Scans skills for security threats (7 analyzers) | internal/audit |
| Config Manager | Loads and merges configuration from multiple layers | internal/config |
Sources: cmd/skillshare/main.go1-281 README.md58-89 High-level Diagram 1
skillshare operates in two distinct modes with different use cases:
| Scenario | Mode | Trigger |
|---|---|---|
Explicit flag -p | Project | User specified |
Explicit flag -g | Global | User specified |
.skillshare/config.yaml exists in cwd | Project | Auto-detect |
No .skillshare/ in cwd | Global | Default |
Mode-agnostic commands (auto-detect): status, diff, list, sync, collect
Mode-explicit commands (require flag): install, update, uninstall, new, target, audit, trash
Global-only commands: push, pull, backup, restore
Global Mode:
push/pull commandsProject Mode:
git clone + install -p + syncSources: skills/skillshare/SKILL.md18-21 skills/skillshare/references/init.md1-92 README.md60-89
skillshare supports 50+ built-in AI CLI targets with three sync modes:
| Mode | Mechanism | Use Case | Local Skills |
|---|---|---|---|
| merge | Per-skill symlinks + manifest | Default, preserves local skills | Preserved |
| copy | Real-file copies + manifest | AIs that can't follow symlinks (Cursor, Copilot CLI) | Preserved |
| symlink | Single directory symlink | Simple setup, destructive | Not possible |
The sync command applies the configured mode per target. Targets are configured in config.yaml with optional per-target filters (include/exclude globs).
Sources: skills/skillshare/references/sync.md12-56 skills/skillshare/references/targets.md82-98 High-level Diagram 4
The audit engine runs automatically during install and update operations, scanning for:
7 Analyzers:
Enforcement:
git reset --hard)Sources: skills/skillshare/references/audit.md1-145 CHANGELOG.md73-223 High-level Diagram 3
Skills can be installed with --track to preserve the .git directory, enabling:
update commandTracked repos are prefixed with _ (e.g., _team-skills) and support nested naming with __ (e.g., _company__frontend__utils).
Sources: skills/skillshare/references/install.md68-86 skills/skillshare/SKILL.md59-64
Project mode enables reproducible team skill setups:
The .skillshare/ directory contains:
config.yaml - Target list and configurationskills/ - Skill source directory.gitignore - Ignores cloned repo artifactsSources: skills/skillshare/SKILL.md57-64 skills/skillshare/references/install.md80-86
The following diagram shows how a typical skill installation flows through the system:
Key Decision Points:
.skillshare/config.yaml exists, otherwise globalSources: cmd/skillshare/main.go46-111 skills/skillshare/SKILL.md31-43 High-level Diagram 2
skillshare provides three entry points for different use cases:
Standard executable installed to /usr/local/bin/skillshare (direct download) or Homebrew-managed path.
Command dispatch occurs at cmd/skillshare/main.go82-100
HTTP server provides a visual interface for non-terminal environments:
Features:
The server auto-downloads UI assets from GitHub releases on first run, cached in ~/.cache/skillshare/ui/.
Sources: skills/skillshare/SKILL.md167-171 CHANGELOG.md103-115
npx-style execution without permanent installation:
The script:
skillshare is in PATH~/.cache/skillshare/bin/ if availableSources: skills/skillshare/scripts/run.sh1-137 README.md123-130
skillshare's 23 commands are organized into functional categories:
| Category | Commands | Purpose |
|---|---|---|
| Core | init, install, uninstall, list, search, sync, status | Essential operations |
| Skill Management | new, check, update, upgrade | Creation and maintenance |
| Target Management | target add/remove/list, diff | Configure sync destinations |
| Sync & Backup | collect, backup, restore, trash | Data movement and recovery |
| Git Remote | push, pull | Cross-machine sync (global mode) |
| Utilities | audit, hub, log, tui, ui, doctor | Security, history, diagnostics |
JSON Output Support (12 commands):
sync, install, update, uninstall, collecttarget list, status, diff, list, check, audit --format json, logWhen --json is specified, commands output structured data to stdout with no spinners or progress text, enabling machine parsing and CI/CD integration.
Sources: cmd/skillshare/main.go18-44 skills/skillshare/SKILL.md114-124 CHANGELOG.md42-64
Configuration is loaded from multiple sources with a clear precedence hierarchy:
Configuration Files:
| File | Location | Purpose |
|---|---|---|
config.yaml | ~/.config/skillshare/ or .skillshare/ | Targets, sync modes, filters, audit settings |
registry.yaml | ~/.config/skillshare/ (optional) | Override built-in target definitions |
audit-rules.yaml | ~/.config/skillshare/ or .skillshare/ | Custom security rules, severity overrides |
Precedence: CLI flags > Project config > Global config > Built-in defaults
Sources: skills/skillshare/references/init.md1-92 High-level Diagram 3
skillshare follows XDG Base Directory specification on Linux/macOS:
| Data Type | Global Path | Project Path | Windows Global |
|---|---|---|---|
| Config | ~/.config/skillshare/ | .skillshare/ | %AppData%\skillshare\ |
| Skills | ~/.config/skillshare/skills/ | .skillshare/skills/ | %AppData%\skillshare\skills\ |
| Cache | ~/.cache/skillshare/ | N/A | %LocalAppData%\skillshare\cache\ |
| Data | ~/.local/share/skillshare/ | .skillshare/ | %AppData%\skillshare\ |
| State | ~/.local/state/skillshare/ | N/A | %AppData%\skillshare\state\ |
Data subdirectories:
backups/ - Target snapshots (global only)trash/ - Soft-deleted skills (7-day retention)ui/ - Cached web dashboard assetsState subdirectories:
logs/ - Operation and audit logsSources: cmd/skillshare/main.go50-55 README.md60-62 skills/skillshare/references/init.md5-8
skillshare provides three levels of interface sophistication:
When stdout is not a terminal (pipes, redirects, CI/CD), output is plain text with no ANSI codes.
Interactive terminal sessions show:
Implemented via pterm library at internal/ui.
Commands list, diff, audit, log, trash list, backup list launch full-screen interactive interfaces when on a TTY:
Features:
/ keyBuilt with charmbracelet/bubbletea following the Elm Architecture (Model-Update-View pattern).
Disable TUI:
--no-tui flag per-commandskillshare tui off globally--json flag (implies --no-tui)Sources: CHANGELOG.md148-156 CHANGELOG.md280-309 High-level Diagram 5
This overview introduced the high-level concepts. For deeper exploration:
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.