Content
# swarmskills
[](https://www.npmjs.com/package/swarmskills)
[](https://www.npmjs.com/package/swarmskills)
[](https://github.com/swarmclawai/swarmskills/blob/main/LICENSE)
[](https://github.com/swarmclawai/swarmskills/actions/workflows/ci.yml)
A CLI and MCP server for managing skills across ~45 code CLI agents.
- **Multi-agent**: Claude Code, Cursor, Codex, Goose, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, OpenHands, Qwen Code, Cline, Continue, Crush, iFlow, Junie, Kiro, Kode, Roo Code, Kilo Code, Antigravity, Amp, Droid, Firebender, Replit, Warp, Augment, Bob, CodeBuddy, Command Code, Cortex Code, Deep Agents, Kimi, MCPJam, Mistral Vibe, OpenClaw, TRAE, TRAE CN, Mux, Neovate, Pi, Pochi, Qoder, Zencoder, AdaL, Hermes — plus user-defined custom tools.
- **CLI**: list, show, search, sync skills across tools; manage Claude Code plugins and marketplaces.
- **MCP server**: 18 tools that let Claude (or any MCP client) discover, install, enable, and sync skills mid-session.
All agents use the same `SKILL.md` + YAML-frontmatter format; `swarmskills` knows where each one looks for them.
## Install
```sh
npm install -g swarmskills
```
Requires Node.js 20+.
## CLI usage
### Multi-agent
```sh
# See every supported tool and which ones are detected on this machine
swarmskills tools list
swarmskills tools list --detected
swarmskills tools detect cursor
# List skills for a specific tool
swarmskills list --tool=cursor
swarmskills list --tool=goose
# List skills across every detected tool
swarmskills list --skills --all-tools
# Search across every detected tool
swarmskills search "test driven" --tool=all
# Show a skill's content from a non-Claude tool
swarmskills show my-skill --tool=cursor
# Register a custom tool
swarmskills tools add-custom myagent /abs/path/to/skills --name "My Agent"
swarmskills tools remove-custom myagent
```
### Set a default tool
Tired of typing `--tool=cursor` every time? Pick a default and `list`, `show`, `search` (without `--tool`) will use it.
```sh
# Interactive picker — shows every detected tool, you choose one
swarmskills tools set-default
# Or pass the key directly
swarmskills tools set-default cursor
swarmskills tools set-default all # default to cross-tool discovery
swarmskills tools get-default # show effective default + sources
swarmskills tools clear-default # revert to claude-code
```
Resolution precedence (highest first):
1. Explicit `--tool=<key>` flag on the command
2. `SWARMSKILLS_DEFAULT_TOOL` environment variable
3. `defaults.tool` in `~/.config/swarmskills/config.json`
4. `claude-code`
### Sync skills across tools
```sh
# Mirror a skill from Claude Code into Cursor + Goose (symlink by default)
swarmskills sync my-skill --from claude-code --to cursor,goose
# Mirror every skill from one tool to another
swarmskills sync --all --from claude-code --to cursor
# Force overwrite, copy instead of symlinking
swarmskills sync my-skill --from claude-code --to cursor --copy --force
```
### Claude Code plugins (Claude-only)
```sh
swarmskills list # plugins + skills for Claude Code
swarmskills enable superpowers@claude-plugins-official
swarmskills disable superpowers@claude-plugins-official
swarmskills install superpowers@claude-plugins-official
swarmskills marketplace list
swarmskills marketplace add my-marketplace owner/repo
swarmskills marketplace refresh claude-plugins-official
```
## MCP server usage
Add to your MCP config (`~/.claude.json` or project `.mcp.json` or any other MCP-aware client):
```json
{
"mcpServers": {
"swarmskills": {
"command": "npx",
"args": ["-y", "swarmskills-mcp"]
}
}
}
```
The server exposes 18 tools:
| Tool | Purpose |
|------|---------|
| `list_skills` | Enumerate skills for a tool, or across all detected tools |
| `show_skill` | Read a skill's full SKILL.md |
| `search_skills` | Fuzzy-search skills, plugins, and marketplace catalogs |
| `list_tools` | Registry of supported CLI agents with detected/installed flags |
| `detect_tool` | Probe a single tool key |
| `add_custom_tool` / `remove_custom_tool` | Register/unregister user-defined CLI agents |
| `get_default_tool` / `set_default_tool` / `clear_default_tool` | Manage the default tool used when no `tool` is passed |
| `sync_skill` | Symlink/copy a skill from one tool to others |
| `list_plugins` | List installed Claude Code plugins |
| `enable_plugin` / `disable_plugin` | Toggle a Claude Code plugin |
| `install_plugin` / `uninstall_plugin` | Manage Claude Code plugins |
| `list_marketplaces` | List Claude Code marketplaces |
| `list_marketplace_catalog` | Show plugins offered by a marketplace |
| `add_marketplace` / `remove_marketplace` | Manage Claude Code marketplaces |
| `refresh_marketplace` | `git pull` a marketplace clone |
> **Restart caveat**: Most CLI agents read their skill state at session start. Mutating tools (`enable`, `install`, `sync`) return `requiresRestart: true` — restart the affected agent for changes to take effect.
For HTTP transport instead of stdio:
```sh
swarmskills-mcp-http --port 4100
```
## Supported tools (built-in)
| Key | Display name | Default skills dir |
|-----|--------------|--------------------|
| `claude-code` | Claude Code | `~/.claude/skills` (+ plugin cache) |
| `cursor` | Cursor | `~/.cursor/skills` |
| `codex` | Codex | `~/.codex/skills` |
| `goose` | Goose | `~/.config/goose/skills` |
| `gemini-cli` | Gemini CLI | `~/.gemini/skills` |
| `github-copilot` | GitHub Copilot | `~/.copilot/skills` |
| `windsurf` | Windsurf | `~/.codeium/windsurf/skills` |
| `opencode` | OpenCode | `~/.config/opencode/skills` |
| `openhands` | OpenHands | `~/.openhands/skills` |
| `qwen-code` | Qwen Code | `~/.qwen/skills` |
| `cline` | Cline | `~/.agents/skills` |
| `continue` | Continue | `~/.continue/skills` |
| `crush` | Crush | `~/.config/crush/skills` |
| `iflow` | iFlow CLI | `~/.iflow/skills` |
| `junie` | Junie | `~/.junie/skills` |
| `kiro` | Kiro CLI | `~/.kiro/skills` |
| `kode` | Kode | `~/.kode/skills` |
| `roo-code` | Roo Code | `~/.roo/skills` |
| `kilo-code` | Kilo Code | `~/.kilocode/skills` |
| `antigravity` | Antigravity | `~/.gemini/antigravity/skills` |
| `amp` | Amp | `~/.config/agents/skills` |
| `droid` | Droid | `~/.factory/skills` |
| `firebender` | Firebender | `~/.firebender/skills` |
| `replit` | Replit | `~/.config/agents/skills` |
| `warp` | Warp | `~/.agents/skills` |
| `augment` | Augment | `~/.augment/skills` |
| `bob` | IBM Bob | `~/.bob/skills` |
| `codebuddy` | CodeBuddy | `~/.codebuddy/skills` |
| `command-code` | Command Code | `~/.commandcode/skills` |
| `cortex` | Cortex Code | `~/.snowflake/cortex/skills` |
| `deepagents` | Deep Agents | `~/.deepagents/agent/skills` |
| `kimi` | Kimi Code CLI | `~/.config/agents/skills` |
| `mcpjam` | MCPJam | `~/.mcpjam/skills` |
| `mistral-vibe` | Mistral Vibe | `~/.vibe/skills` |
| `mux` | Mux | `~/.mux/skills` |
| `neovate` | Neovate | `~/.neovate/skills` |
| `openclaw` | OpenClaw | `~/.openclaw/skills` |
| `pi` | Pi | `~/.pi/agent/skills` |
| `pochi` | Pochi | `~/.pochi/skills` |
| `qoder` | Qoder | `~/.qoder/skills` |
| `trae` | TRAE IDE | `~/.trae/skills` |
| `trae-cn` | TRAE CN | `~/.trae-cn/skills` |
| `zencoder` | Zencoder | `~/.zencoder/skills` |
| `adal` | AdaL | `~/.adal/skills` |
| `hermes` | Hermes Agent | `~/.hermes/skills` (recursive) |
Path list cribbed from [`xingkongliang/skills-manager`](https://github.com/xingkongliang/skills-manager) — credit where due.
`.config/...` paths also honour `XDG_CONFIG_HOME` when set. Need a tool that's not on this list? `swarmskills tools add-custom <key> <skillsDir>`.
## How it works
For each tool, swarmskills resolves the on-disk skills directory and parses the YAML frontmatter from each `SKILL.md`. Claude Code additionally has plugin-bundled skills under `~/.claude/plugins/cache/<marketplace>/<plugin>/skills/`, surfaced via the same `list_skills` API.
State managed:
- `~/.claude/skills/` — Claude Code standalone skills
- `~/.claude/plugins/installed_plugins.json` — Claude plugin registry
- `~/.claude/plugins/known_marketplaces.json` — Claude marketplace registry
- `~/.claude/settings.json` `enabledPlugins` — Claude per-plugin enabled flags
- `~/.config/swarmskills/config.json` — swarmskills's own config (custom tools, defaults)
All writes are atomic (write to `.tmp` then rename).
To run against a non-default home for testing:
```sh
SWARMSKILLS_HOME=/path/to/fake-home swarmskills tools list
```
## Development
```sh
pnpm install
pnpm test
pnpm build
```
## License
MIT © SwarmClaw AI
