Files
skillshare/README.md
T
Willie 684b0da971 docs: add v0.15.4 changelog, update SKILL.md, README, and UI for supply-chain security
- Add v0.15.4 CHANGELOG entry (audit gate, content hash pinning, --diff,
  source-repository-link rule, severity-based risk floor, bug fixes)
- Bump SKILL.md version to v0.15.4 with supply-chain security keywords
- Update README Recent Updates table to reference v0.15.4
- Fix security.md rule count 25→31 to match audit.md
- DashboardPage: include blocked count in update summary toast
- SkillDetailPage: show ConfirmDialog on blocked update with
  "Skip Audit & Update" retry option
2026-02-23 04:18:01 +08:00

455 lines
20 KiB
Markdown

<p align="center" style="margin-bottom: 0;">
<img src=".github/assets/logo.png" alt="skillshare" width="280">
</p>
<h1 align="center" style="margin-top: 0.5rem; margin-bottom: 0.5rem;">skillshare</h1>
<p align="center">
<a href="https://skillshare.runkids.cc"><img src="https://img.shields.io/badge/Website-skillshare.runkids.cc-blue?logo=docusaurus" alt="Website"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
<a href="go.mod"><img src="https://img.shields.io/github/go-mod/go-version/runkids/skillshare" alt="Go Version"></a>
<a href="https://github.com/runkids/skillshare/releases"><img src="https://img.shields.io/github/v/release/runkids/skillshare" alt="Release"></a>
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue" alt="Platform">
<a href="https://goreportcard.com/report/github.com/runkids/skillshare"><img src="https://goreportcard.com/badge/github.com/runkids/skillshare" alt="Go Report Card"></a>
<a href="https://deepwiki.com/runkids/skillshare"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
</p>
<p align="center">
<a href="https://github.com/runkids/skillshare/stargazers"><img src="https://img.shields.io/github/stars/runkids/skillshare?style=social" alt="Star on GitHub"></a>
</p>
<p align="center">
<strong>One source of truth for AI CLI skills. Sync everywhere with one command — from personal to organization-wide.</strong><br>
Claude Code, OpenClaw, OpenCode & 49+ more.
</p>
<p align="center">
<img src=".github/assets/demo.gif" alt="skillshare demo" width="960">
</p>
<p align="center">
<a href="https://skillshare.runkids.cc">Website</a> •
<a href="#installation">Install</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#cli-and-ui-preview">Screenshots</a> •
<a href="#common-workflows">Commands</a> •
<a href="#web-dashboard">Web UI</a> •
<a href="#project-skills-per-repo">Project Skills</a> •
<a href="#organization-skills-tracked-repo">Organization Skills</a> •
<a href="#skill-hub">Hub</a> •
<a href="https://skillshare.runkids.cc/docs">Docs</a>
</p>
> [!NOTE]
> **Recent Updates**
> | Version | Highlights |
> |---------|------------|
> | [0.15.x](https://github.com/runkids/skillshare/releases/tag/v0.15.4) | Supply-chain security (auto-audit gate with rollback, content hash pinning, `--diff` for `update`), copy sync mode, HTTPS token auth, multi-name `audit` with `--group` |
> | [0.14.0](https://github.com/runkids/skillshare/releases/tag/v0.14.0) | Global skill manifest, `.skillignore`, multi-skill/group uninstall, license display, 6 new audit rules |
> | [0.13.0](https://github.com/runkids/skillshare/releases/tag/v0.13.0) | Skill-level targets, XDG compliance, unified target names, runtime UI download |
> | [0.12.0](https://github.com/runkids/skillshare/releases/tag/v0.12.0) | Skill Hub — generate indexes, search private catalogs with `--hub` |
## Why skillshare
Stop managing skills tool-by-tool.
`skillshare` gives you one shared skill source and pushes it everywhere your AI agents work.
- **One command, everywhere**: Sync to Claude Code, Codex, Cursor, OpenCode, and more with `skillshare sync`.
- **Safe by default**: Non-destructive merge mode keeps CLI-local skills intact while sharing team skills.
- **True bidirectional flow**: Pull skills back from targets with `collect` so improvements never get trapped in one tool.
- **Cross-machine ready**: Git-native `push`/`pull` keeps all your devices aligned.
- **Team + project friendly**: Use global skills for personal workflows and `.skillshare/` for repo-scoped collaboration.
- **Folder-friendly**: Organize skills in folders (e.g. `frontend/react/`) — auto-flattened to flat names on sync.
- **Privacy-first**: No central registry, no telemetry, no install tracking. Your skill setup stays entirely local.
- **Built-in security audit**: Scan skills for prompt injection, data exfiltration, and other threats before they reach your AI agent.
- **Visual control panel**: Open `skillshare ui` for browsing, install, target management, and sync status in one place.
## Comparison
skillshare uses a **declarative** approach: define your targets once in `config.yaml`, then `sync` handles everything — no prompts, no repeated selections.
| | Imperative (install-per-command) | Declarative (skillshare) |
|---|---|---|
| **Config** | No config; prompts every run | `config.yaml` — set once |
| **Agent selection** | Interactive prompt each time | Defined in config |
| **Install method** | Choose per operation | `sync_mode` in config |
| **Source of truth** | Skills copied independently | Single source → symlinks (or copies) |
| **Remove one agent's skill** | May break other agents' symlinks | Only that target's symlink removed |
| **New machine setup** | Re-run every install manually | `git clone` config + `sync` |
| **Project-scoped skills** | Global lock file only | `init -p` for per-repo skills |
| **Cross-machine sync** | Manual | Built-in `push` / `pull` |
| **Bidirectional** | Install only | `collect` pulls changes back |
| **Security audit** | None | Built-in `audit` + auto-scan on install |
| **Web dashboard** | None | `skillshare ui` |
| **Runtime dependency** | Node.js + npm | None (single Go binary) |
> [!TIP]
> Coming from another tool? See the [Migration Guide](https://skillshare.runkids.cc/docs/guides/migration) and [detailed comparison](https://skillshare.runkids.cc/docs/guides/comparison).
## How It Works
- macOS / Linux: `~/.config/skillshare/skills/`
- Windows: `%AppData%\skillshare\skills\`
```
┌─────────────────────────────────────────────────────────────┐
│ Source Directory │
│ ~/.config/skillshare/skills/ │
└─────────────────────────────────────────────────────────────┘
│ sync
┌───────────────┼───────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Claude │ │ OpenCode │ │ OpenClaw │ ...
└───────────┘ └───────────┘ └───────────┘
```
| Platform | Source Path | Link Type |
|----------|-------------|-----------|
| macOS/Linux | `~/.config/skillshare/skills/` | Symlinks |
| Windows | `%AppData%\skillshare\skills\` | NTFS Junctions (no admin required) |
> Targets that can't follow symlinks? Use `skillshare target <name> --mode copy` to sync as real files instead.
> [!TIP]
> Skills can be organized in folders (e.g. `frontend/react/react-best-practices/`) — they're auto-flattened on sync. See the [Organizing Guide](https://skillshare.runkids.cc/docs/guides/organizing-skills) and [runkids/my-skills](https://github.com/runkids/my-skills) for a real-world example.
## CLI and UI Preview
### CLI
| Sync | Install + Audit |
|---|---|
| <img src=".github/assets/sync-collision-demo.png" alt="CLI sync output" width="480" height="280" style="object-fit: cover;"> | <img src=".github/assets/install-with-audio-demo.png" alt="CLI install with security audit" width="480" height="280" style="object-fit: cover;"> |
### UI
| Dashboard | Security Audit |
|---|---|
| <img src=".github/assets/ui/web-dashboard-demo.png" alt="Web dashboard overview" width="480" height="280" style="object-fit: cover;"> | <img src=".github/assets/ui/web-audit-demo.png" alt="Web UI security audit" width="480" height="280" style="object-fit: cover;"> |
## Installation
### macOS / Linux
```bash
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
```
### Windows PowerShell
```powershell
irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex
```
### Homebrew
```bash
brew install skillshare
```
> **Note:** All install methods include the web dashboard. `skillshare ui` automatically downloads UI assets on first launch — no extra setup needed.
> **Tip:** To update to the latest version, run `skillshare upgrade`. It auto-detects your install method (Homebrew, manual, etc.) and handles the rest.
### Shorthand (Optional)
Add an alias to your shell config (`~/.zshrc` or `~/.bashrc`):
```bash
alias ss='skillshare'
```
### Uninstall
```bash
# macOS/Linux
brew uninstall skillshare # Homebrew
sudo rm /usr/local/bin/skillshare # Manual install
rm -rf ~/.config/skillshare # Config & skills (optional)
rm -rf ~/.local/share/skillshare # Backups & trash (optional)
rm -rf ~/.local/state/skillshare # Logs (optional)
rm -rf ~/.cache/skillshare # UI & version cache (optional)
# Windows (PowerShell)
Remove-Item "$env:LOCALAPPDATA\Programs\skillshare" -Recurse -Force
Remove-Item "$env:APPDATA\skillshare" -Recurse -Force # optional
```
---
## Quick Start
```bash
skillshare init --dry-run # Preview setup
skillshare init # Create config, source, and detected targets
skillshare sync # Sync skills to all targets
```
## Common Workflows
### Daily Commands
| Command | What it does |
|---------|---------------|
| `skillshare list` | List skills in source |
| `skillshare status` | Show sync status for all targets |
| `skillshare sync` | Sync source skills to all targets |
| `skillshare diff` | Preview differences before syncing |
| `skillshare doctor` | Diagnose config/environment issues |
| `skillshare new <name>` | Create a new skill template |
| `skillshare install [source]` | Install skill from source, or all skills from config (no args) |
| `skillshare collect [target]` | Import skills from target(s) back to source |
| `skillshare update <name>` | Update one installed skill/repo |
| `skillshare update --all` | Update all tracked repos |
| `skillshare uninstall <name>... [-G <group>]` | Remove skill(s) or groups from source |
| `skillshare audit [name]` | Scan skills for security threats |
| `skillshare log` | View operations and audit logs for debugging and compliance |
| `skillshare search <query>` | Search installable skills on GitHub |
| `skillshare search --hub [url]` | Search a hub index (default: skillshare-hub) |
| `skillshare hub index` | Generate a hub index from installed skills |
`skillshare search` requires GitHub auth (`gh auth login`) or `GITHUB_TOKEN`. The `--hub` flag searches a JSON index instead — without a URL it defaults to the public [skillshare-hub](https://github.com/runkids/skillshare-hub).
### Target Management
```bash
skillshare target list
skillshare target add my-tool ~/.my-tool/skills
skillshare target remove my-tool
```
### Backup and Restore
```bash
skillshare backup
skillshare backup --list
skillshare restore <target>
```
### Cross-machine Git Sync
```bash
skillshare push
skillshare pull
```
### Project Skills (Per Repo)
```bash
skillshare init -p
skillshare new my-skill -p
skillshare install anthropics/skills/skills/pdf -p
skillshare install github.com/team/skills --track -p
skillshare sync
```
Project mode keeps skills in `.skillshare/skills/` so they can be committed and shared with the repo. In both global and project mode, `config.yaml` acts as a **portable skill manifest** — run `skillshare install` with no arguments to install all listed skills:
```bash
# Global — new machine setup
skillshare install # Installs all skills from ~/.config/skillshare/config.yaml
skillshare sync
# Project — new team member onboarding
git clone github.com/your/project && cd project
skillshare install -p # Installs all skills from .skillshare/config.yaml
skillshare sync
```
### Organization Skills (Tracked Repo)
```bash
skillshare install github.com/team/skills --track
skillshare update _team-skills
skillshare sync
```
## Skill Hub
Build a searchable skill catalog for your organization — no GitHub API required.
```bash
skillshare hub index # Generate index from installed skills
skillshare search --hub # Browse the public skillshare-hub
skillshare search react --hub # Search "react" in skillshare-hub
skillshare search --hub ./skillshare-hub.json react # Search custom local index
skillshare search --hub https://example.com/hub.json # Search custom remote index
```
The generated `skillshare-hub.json` follows a versioned schema (`schemaVersion: 1`) with support for tags and multi-skill repos. Host it on any static server, internal CDN, or commit it alongside your skills repo.
The public hub at [runkids/skillshare-hub](https://github.com/runkids/skillshare-hub) is the built-in default. Fork it to bootstrap your organization's internal hub — CI validation and `skillshare audit` security scans are included out of the box.
> [!TIP]
> See the [Hub Index Guide](https://skillshare.runkids.cc/docs/guides/hub-index) for schema details and hosting options.
## Web Dashboard
```bash
skillshare ui # Global mode
skillshare ui -p # Project mode (manages .skillshare/)
```
- Opens `http://127.0.0.1:19420`
- Requires `skillshare init` (or `init -p` for project mode) first
- Auto-detects project mode when `.skillshare/config.yaml` exists
- UI assets are downloaded on first launch (~1 MB), then cached offline at `~/.cache/skillshare/ui/`
For containers/remote hosts:
```bash
skillshare ui --host 0.0.0.0 --no-open
```
Then access: `http://localhost:19420`
## Security Audit
Scan installed skills for prompt injection, data exfiltration, credential theft, and other threats before they reach your AI agent.
```bash
skillshare audit # Scan all skills
skillshare audit <name> # Scan a specific skill
```
Skills are also scanned automatically during `skillshare install`.
- `skillshare install` runs an audit by default.
- Block threshold is configurable with `audit.block_threshold` (`CRITICAL` default; also supports `HIGH`, `MEDIUM`, `LOW`, `INFO`).
- `audit.block_threshold` only controls blocking level; it does **not** disable scanning.
- There is no config flag to permanently skip audit. To bypass a single install, use `--skip-audit`.
- Use `--force` to override blocked installs while still running audit (findings remain visible).
- Use `--skip-audit` to bypass scanning for a single install command.
- If both are set, `--skip-audit` takes precedence in practice (audit is not executed).
> [!TIP]
> See the [Securing Your Skills](https://skillshare.runkids.cc/docs/guides/security) guide for a complete security workflow, or the [audit command reference](https://skillshare.runkids.cc/docs/commands/audit) for the full list of detection patterns.
## Docker
Use Docker for reproducible testing, interactive playgrounds, and production deployment.
### Test pipeline
```bash
make test-docker # offline sandbox (build + unit + integration)
```
### Interactive playground
```bash
make playground # start + enter shell (one step)
make playground-down # stop and remove
# Advanced sandbox management:
./scripts/sandbox.sh <up|down|shell|reset|status|logs|bare>
```
Inside the playground:
```bash
skillshare status # global mode (pre-initialized)
skillshare list # see flat + nested skills
skillshare-ui # start global-mode dashboard (:19420)
# Project mode (pre-configured demo project)
cd ~/demo-project
skillshare status # auto-detects project mode
skillshare-ui-p # project mode dashboard (:19420)
```
### Dev profile
```bash
# With Go installed locally (single command):
make ui-dev # Go API server + Vite HMR together
# Without Go (API in Docker):
make dev-docker # Go API server in Docker (:19420)
cd ui && pnpm run dev # Vite dev server on host (:5173)
make dev-docker-down # stop when done
```
### Production image
```bash
make docker-build # build production image
make docker-build-multiarch # build for amd64 + arm64
```
Pre-built images are published to [GitHub Packages](https://github.com/runkids/skillshare/pkgs/container/skillshare) on each release.
## Development
**Recommended:** Open in [Dev Containers](https://containers.dev/) — Go toolchain, Node.js, pnpm, and demo content are pre-configured. All dev servers (API, Vite, Docusaurus) start automatically.
```bash
make build # build binary
make test # unit + integration tests
make lint # go vet
make fmt # format Go files
make check # fmt + lint + test
make ui-dev # Go API server + Vite HMR together
make build-all # frontend + Go binary
```
## Documentation
- Docs home: https://skillshare.runkids.cc/docs/
- Commands: https://skillshare.runkids.cc/docs/commands
- Guides: https://skillshare.runkids.cc/docs/guides/
- Troubleshooting: https://skillshare.runkids.cc/docs/troubleshooting/faq
## Contributing
Contributions are welcome! Here's the recommended workflow:
1. **Open an issue first** — describe what you'd like to change and why. This helps align on scope and approach before writing code.
2. **Submit a draft PR** — if you'd like to propose an implementation, open a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) and link it to the issue. Draft PRs let us collaborate on the approach early, before investing time in polish.
3. **Include tests** — PRs that include test coverage are much easier to review and merge. Run `make check` (format + lint + test) to verify before submitting.
```bash
git clone https://github.com/runkids/skillshare.git
cd skillshare
make check # format + lint + test (must pass)
```
Or open in [Dev Containers](https://containers.dev/) for a zero-setup environment.
> [!TIP]
> Not sure where to start? Browse [open issues](https://github.com/runkids/skillshare/issues) or open a new one to discuss your idea.
## Contributors
Thanks to everyone who helped shape skillshare through issues, PRs, and ideas.
<a href="https://github.com/leeeezx"><img src="https://github.com/leeeezx.png" width="40" height="40" alt="leeeezx"></a>
<a href="https://github.com/xocasdashdash"><img src="https://github.com/xocasdashdash.png" width="40" height="40" alt="xocasdashdash"></a>
<a href="https://github.com/romanr"><img src="https://github.com/romanr.png" width="40" height="40" alt="romanr"></a>
<a href="https://github.com/philippe-granet"><img src="https://github.com/philippe-granet.png" width="40" height="40" alt="philippe-granet"></a>
<a href="https://github.com/terranc"><img src="https://github.com/terranc.png" width="40" height="40" alt="terranc"></a>
<a href="https://github.com/benrfairless"><img src="https://github.com/benrfairless.png" width="40" height="40" alt="benrfairless"></a>
<a href="https://github.com/nerveband"><img src="https://github.com/nerveband.png" width="40" height="40" alt="nerveband"></a>
<a href="https://github.com/EarthChen"><img src="https://github.com/EarthChen.png" width="40" height="40" alt="EarthChen"></a>
<a href="https://github.com/gdm257"><img src="https://github.com/gdm257.png" width="40" height="40" alt="gdm257"></a>
<a href="https://github.com/skovtunenko"><img src="https://github.com/skovtunenko.png" width="40" height="40" alt="skovtunenko"></a>
<a href="https://github.com/TyceHerrman"><img src="https://github.com/TyceHerrman.png" width="40" height="40" alt="TyceHerrman"></a>
<a href="https://github.com/1am2syman"><img src="https://github.com/1am2syman.png" width="40" height="40" alt="1am2syman"></a>
<a href="https://github.com/thealokkr"><img src="https://github.com/thealokkr.png" width="40" height="40" alt="thealokkr"></a>
<a href="https://github.com/njg7194"><img src="https://github.com/njg7194.png" width="40" height="40" alt="njg7194"></a>
---
If you find skillshare useful, consider giving it a ⭐
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=runkids/skillshare&type=date&legend=top-left)](https://www.star-history.com/#runkids/skillshare&type=date&legend=top-left)
---
## License
MIT