From 2b2d8014d654cfff6ce8f0a656e47c098687f3e9 Mon Sep 17 00:00:00 2001 From: Willie Date: Sun, 8 Feb 2026 16:41:09 +0800 Subject: [PATCH] docs: reorganize README and refresh messaging --- README.md | 446 +++++++++++++++++------------------------------------- 1 file changed, 141 insertions(+), 305 deletions(-) diff --git a/README.md b/README.md index 64881b30a..18e377f75 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,8 @@

- One source of truth for AI CLI skills. Sync everywhere with one command — from personal to organization-wide.
- Claude Code, OpenClaw, OpenCode & 40+ more. + One source of truth for AI CLI skills.
+ Sync once, use everywhere: Claude Code, Codex, Cursor, OpenCode, and more.

@@ -31,10 +31,11 @@ Website • Install • Quick Start • - Commands • + Screenshots • + Commands • Web UI • - Project Skills • - Organization Skills • + Project Skills • + Organization Skills • Docs

@@ -46,36 +47,53 @@ > | [0.9.0](https://github.com/runkids/skillshare/releases/tag/v0.9.0) | Project-level skills — scope skills to a single repo, share via git | > | [0.8.0](https://github.com/runkids/skillshare/releases/tag/v0.8.0) | `pull` → `collect` rename, clearer command symmetry, refactoring | -## Why skillshare? +## Why skillshare -Install tools get skills onto agents. **Skillshare keeps them in sync.** +Stop managing skills tool-by-tool. +`skillshare` gives you one shared skill source and pushes it everywhere your AI agents work. -| Feature | Description | -|---------|-------------| -| 🔗 **Non-destructive Merge** | Sync shared skills while preserving CLI-specific ones. Per-skill symlinks keep local skills untouched. | -| ↔️ **Bidirectional Sync** | Created a skill in Claude? Collect it back to source and share with OpenClaw, OpenCode, and others. | -| 🌐 **Cross-machine Sync** | One git push/pull syncs skills across all your machines. No re-running install commands. | -| 📦 **Unified Source** | Local skills and installed skills live together in one directory. No separate management. | -| 👥 **Organization Skills** | Install shared repos once, update anytime with git pull. Changes sync to all agents instantly. | -| 📁 **Project Skills** | Scope skills to a repo, share via git. Auto-detected when you `cd` into the project. | -| ✨ **AI-Native** | Built-in skill lets AI operate skillshare directly. No manual CLI needed. | -| 🖥️ **Web Dashboard** | Visual skill browsing, sync status, and management. Run `skillshare ui` — single binary, no setup. | +- **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. +- **Visual control panel**: Open `skillshare ui` for browsing, install, target management, and sync status in one place. + +## CLI and UI Preview + +### CLI + +| Status | Search | +|---|---| +| CLI status command output | CLI search command output | + +### UI + +| Dashboard | Skills | +|---|---| +| Web dashboard overview | Web UI skills browser | + +### Windows + +

+ Windows initialization demo +

## Installation -### Quick Install (macOS/Linux) +### macOS / Linux ```bash curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh ``` -### Quick Install (Windows PowerShell) +### Windows PowerShell ```powershell irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex ``` -### Homebrew (macOS) +### Homebrew ```bash brew install runkids/tap/skillshare @@ -94,346 +112,170 @@ Remove-Item "$env:LOCALAPPDATA\Programs\skillshare" -Recurse -Force Remove-Item "$env:USERPROFILE\.config\skillshare" -Recurse -Force # optional ``` -### Shorthand (Optional) - -Add an alias to your shell config (`~/.zshrc` or `~/.bashrc`): - -```bash -alias ss='skillshare' -``` - ## Quick Start ```bash skillshare init --dry-run # Preview setup -skillshare init # Auto-detects CLIs, sets up git -skillshare sync # Sync to all targets +skillshare init # Create config, source, and detected targets +skillshare sync # Sync skills to all targets ``` -Done. Your skills are now synced across all AI CLI tools. +Default source directory: -## How It Works +- macOS / Linux: `~/.config/skillshare/skills/` +- Windows: `%USERPROFILE%\.config\skillshare\skills\` -``` -┌─────────────────────────────────────────────────────────────┐ -│ Source Directory │ -│ ~/.config/skillshare/skills/ │ -└─────────────────────────────────────────────────────────────┘ - │ sync - ┌───────────────┼───────────────┐ - ▼ ▼ ▼ - ┌───────────┐ ┌───────────┐ ┌───────────┐ - │ Claude │ │ OpenCode │ │ OpenClaw │ ... - └───────────┘ └───────────┘ └───────────┘ +## 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 ` | Create a new skill template | +| `skillshare install ` | Install skill from local path or git source | +| `skillshare collect [target]` | Import skills from target(s) back to source | +| `skillshare update ` | Update one installed skill/repo | +| `skillshare update --all` | Update all tracked repos | +| `skillshare uninstall ` | Remove skill from source | +| `skillshare search ` | Search installable skills on GitHub | + +`skillshare search` requires GitHub auth (`gh auth login`) or `GITHUB_TOKEN`. + +### Target Management + +```bash +skillshare target list +skillshare target add my-tool ~/.my-tool/skills +skillshare target remove my-tool ``` -| Platform | Source Path | Link Type | -|----------|-------------|-----------| -| macOS/Linux | `~/.config/skillshare/skills/` | Symlinks | -| Windows | `%USERPROFILE%\.config\skillshare\skills\` | NTFS Junctions (no admin required) | +### Backup and Restore -

- Windows init demo -

+```bash +skillshare backup +skillshare backup --list +skillshare restore +``` -## Documentation +### Cross-machine Git Sync -📖 **Full documentation at [skillshare.runkids.cc](https://skillshare.runkids.cc/docs/intro)** +```bash +skillshare push +skillshare pull +``` -| Guide | Description | -|-------|-------------| -| [Getting Started](https://skillshare.runkids.cc/docs/intro) | Quick start guide | -| [Commands](https://skillshare.runkids.cc/docs/commands/init) | All CLI commands | -| [Web Dashboard](https://skillshare.runkids.cc/docs/commands/ui) | Visual skill management via browser | -| [Project Skills](https://skillshare.runkids.cc/docs/guides/project-setup) | Project-level skills setup | -| [Organization Skills](https://skillshare.runkids.cc/docs/guides/organization-sharing) | Organization-wide sharing with tracked repos | -| [Cross-machine](https://skillshare.runkids.cc/docs/guides/cross-machine-sync) | Multi-machine sync | -| [Docker Sandbox](https://skillshare.runkids.cc/docs/guides/docker-sandbox) | Test sandbox and interactive playground | -| [FAQ](https://skillshare.runkids.cc/docs/troubleshooting/faq) | FAQ & troubleshooting | +### Project Skills (Per Repo) -## Commands +```bash +skillshare init -p +skillshare new my-skill -p +skillshare install anthropics/skills/skills/pdf -p +skillshare sync +``` -| Command | Description | -|---------|-------------| -| `init` | Initialize, auto-detect CLIs, setup git | -| `new ` | Create a new skill with SKILL.md template | -| `search ` | Search GitHub for skills | -| `sync` | Sync skills to all targets | -| `collect ` | Collect skills from target back to source | -| `push` | Push to git remote (cross-machine) | -| `pull` | Pull from git remote and sync | -| `install ` | Install skill from path or git repo | -| `uninstall ` | Remove skill from source | -| `update ` | Update skill or tracked repo | -| `list` | List installed skills | -| `status` | Show sync state | -| `doctor` | Diagnose issues | -| `upgrade` | Upgrade CLI and skill | -| `ui` | [Launch web dashboard](#web-dashboard) | +Project mode keeps skills in `.skillshare/skills/` so they can be committed and shared with the repo. + +### Organization Skills (Tracked Repo) + +```bash +skillshare install github.com/team/skills --track +skillshare update _team-skills +skillshare sync +``` ## Web Dashboard -Launch a visual dashboard to browse skills, manage targets, sync, search, and edit config — all from your browser. - ```bash skillshare ui ``` -Opens `http://localhost:19420` with a full-featured React dashboard embedded in the binary. No Node.js or extra setup required. +- Opens `http://127.0.0.1:19420` +- Requires `skillshare init` first +- Runs from the same CLI binary (no extra frontend setup) -| Page | What you can do | -|------|----------------| -| Dashboard | Overview of skills, targets, sync mode, version | -| Skills | Browse and filter skills, view SKILL.md content, uninstall | -| Install | Install from local path, git URL, or GitHub shorthand | -| Targets | View status, add/remove targets | -| Sync | Run sync with dry-run/force toggles, preview diffs | -| Collect | Collect skills from targets back to source with picker flow | -| Backup | Browse backups, restore, and clean up old snapshots | -| Git Sync | Push/pull source repo, check dirty state, force pull when needed | -| Search | Search GitHub for skills, one-click install | -| Config | Edit config.yaml with validation | - -### UI Preview - -| Install Flow | Dashboard Overview | -|---|---| -| web install flow | web dashboard overview | - -| Skills Browser | Skill Detail | -|---|---| -| web skills browser | web skill detail | - -| Sync Controls | Search Skills | -|---|---| -| web sync controls | web search skills | - -Also works in Docker: `skillshare ui --host 0.0.0.0 --no-open` (port 19420 is mapped). - ---- - -## Docker Sandbox Testing - -Use Docker to run reproducible tests in an isolated environment. - -Guide: [Docker Sandbox Guide](https://skillshare.runkids.cc/docs/guides/docker-sandbox) - -With `mise`: +For containers/remote hosts: ```bash -mise run test:docker +skillshare ui --host 0.0.0.0 --no-open ``` -With `make`: +Then access: `http://localhost:19420` + +## Docker Sandbox + +Use Docker for reproducible offline testing and an interactive playground. + +### Offline test pipeline ```bash make test-docker +# or +./scripts/test_docker.sh ``` -This offline sandbox runs Go `build + unit + integration` with `network_mode: none`. -It covers install/update flows based on local paths and `file://` git repositories. - -Run optional network-dependent install/update checks separately: - -With `mise`: - -```bash -mise run test:docker:online -``` - -With `make`: +### Optional online install/update checks ```bash make test-docker-online +# or +./scripts/test_docker_online.sh ``` -You can also pass custom commands: - -```bash -./scripts/test_docker.sh --cmd "go test -v ./tests/integration/..." -./scripts/test_docker_online.sh --cmd "go test -v -tags online ./tests/integration/... -run TestInstall_Remote" -``` - -### Interactive Playground - -Use a dedicated persistent container for manually exploring skillshare commands. - -With `mise`: - -```bash -mise run sandbox:up -mise run sandbox:shell -``` - -With `make`: +### Interactive playground ```bash make sandbox-up make sandbox-shell -``` - -Inside the container you can run directly (no manual build needed): - -```bash -skillshare --help -ss --help -skillshare init --dry-run -skillshare ui --host 0.0.0.0 --no-open # Web UI at http://localhost:19420 -``` - -Stop the playground when done: - -With `mise`: - -```bash -mise run sandbox:down -``` - -With `make`: - -```bash make sandbox-down ``` -### Target Management +Inside the playground: ```bash -skillshare target list # List targets -skillshare target add myapp ~/.myapp/skills # Add custom target -skillshare target remove claude # Safely unlink +skillshare --help +skillshare init --dry-run +skillshare ui --host 0.0.0.0 --no-open ``` ---- - -## AI-Native - -The built-in [`skillshare` skill](https://github.com/runkids/skillshare/tree/main/skills/skillshare) teaches your AI how to manage skills. The binary auto-downloads on first use. - -``` -User: "sync my skills to all targets" - │ - ▼ -AI reads skillshare skill → runs: skillshare sync - │ - ▼ -✓ Synced 5 skills to claude, codex, cursor -``` - -> **Try it:** *"Show my skillshare status"*, *"Collect skills from Claude"*, *"Install the pdf skill from anthropics/skills"* - ---- - -## Search Skills - -Discover and install skills from GitHub with interactive search. +## Development ```bash -skillshare search runkids +go build -o bin/skillshare ./cmd/skillshare +go test ./... +go vet ./... +gofmt -w ./cmd ./internal ./tests ``` -

- search demo -

- -**Features:** -- **Smart ranking** — Results sorted by repository stars -- **Interactive selector** — Arrow keys to navigate, Enter to install -- **Continuous search** — Search again without restarting -- **Filter forks** — Only shows original repositories +Using `make`: ```bash -skillshare search pdf --list # List only, no install prompt -skillshare search react --json # JSON output for scripting -skillshare search commit -n 5 # Limit results +make build +make test +make lint +make fmt +make check ``` -> **Note:** Requires GitHub authentication. Run `gh auth login` or set `GITHUB_TOKEN`. - -See [Search Guide](https://skillshare.runkids.cc/docs/commands/search) for details. - ---- - -## Project Skills - -Scope skills to a single repository — shared with your team via git. +UI development helpers: ```bash -# Initialize project-level skills -skillshare init -p - -# Create or install skills -skillshare new my-skill -p -skillshare install anthropics/skills/skills/pdf -p - -# Sync to targets -skillshare sync +make ui-install +make ui-build +make ui-dev +make build-ui ``` -**Features:** -- **Project-scoped** — Skills live in `.skillshare/skills/`, committed to the project repo -- **Auto-detection** — Commands auto-detect project mode when `.skillshare/` exists -- **Team onboarding** — New members run `skillshare install -p && skillshare sync` -- **Coexists with global** — Project and global skills work independently +## Documentation -See [Project Skills Guide](https://skillshare.runkids.cc/docs/guides/project-setup) for details. - ---- - -## Organization Skills - -Share skills across your organization with tracked repositories. - -```bash -# Install team repo -skillshare install github.com/team/skills --track - -# Update later -skillshare update _team-skills -skillshare sync -``` - -**Features:** -- **Tracked repos** — Clone with `.git`, update via `git pull` -- **Nested skills** — `team/frontend/ui` → `team__frontend__ui` -- **Auto-pruning** — Orphaned symlinks removed on sync -- **Collision detection** — Warns about duplicate skill names - -See [Organization Skills Guide](https://skillshare.runkids.cc/docs/guides/organization-sharing) for details. - ---- - -## FAQ - -**What if I modify a skill in a target directory?** - -Since targets are linked to source, you're editing the source directly. All targets see changes immediately. - -**How do I keep CLI-specific skills?** - -Use `merge` mode (default). Local skills in targets are preserved. - -**Accidentally deleted a skill?** - -Recover with git: `cd ~/.config/skillshare/skills && git checkout -- deleted-skill/` - -**Windows: Do I need admin privileges?** - -No. skillshare uses NTFS junctions (not symlinks), which don't require elevated permissions. - -See [FAQ & Troubleshooting](https://skillshare.runkids.cc/docs/troubleshooting/faq) for more. - ---- - -## Common Issues - -| Issue | Solution | -|-------|----------| -| `config not found` | Run `skillshare init` | -| Deleted source via symlink | Use `skillshare target remove`, recover via git | -| Target exists with files | Run `skillshare backup` first | -| Skill not appearing | Run `skillshare doctor`, restart CLI | - ---- +- Docs home: https://skillshare.runkids.cc/docs/intro +- Commands: https://skillshare.runkids.cc/docs/category/commands +- Guides: https://skillshare.runkids.cc/docs/category/guides +- Troubleshooting: https://skillshare.runkids.cc/docs/troubleshooting/faq ## Contributing @@ -444,13 +286,7 @@ go build -o bin/skillshare ./cmd/skillshare go test ./... ``` -[Open an issue](https://github.com/runkids/skillshare/issues) for bugs or feature requests. - -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) +Issues and PRs are welcome: https://github.com/runkids/skillshare/issues ## License