Skip to content

Install a Claude Code plugin#

Goal: install any Claude Code marketplace plugin into swarm and have all its surfaces (skills, commands, sub-agents, hooks, MCP servers) register. Time: 5 minutes.

swarm's plugin loader is fully compatible with the CC-format. No format conversion needed.

1. Get a plugin#

From the official marketplace:

git clone https://github.com/obra/superpowers /tmp/superpowers

Or from your ~/.claude/plugins/cache/... if you already have Claude Code installed.

2. Install#

swarm plugins install /tmp/superpowers

Or via REST:

curl -X POST http://localhost:8000/api/v1/plugins \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_path": "/tmp/superpowers"}'

Or via dashboard: Plugins → Install → paste path → Install.

3. Verify everything registered#

swarm plugins list

For superpowers v5.0.7 you'll see:

NAME           VERSION  SKILLS  CMDS  AGENTS  HOOKS  MCP
superpowers    5.0.7    14      3     1       1      0

If you see SKILLS=0 when the plugin has them on disk, check that the feature flag is on:

swarm features set skill_registry on
swarm plugins reload superpowers

4. Verified compat matrix#

We regression-test against 16 real CC plugins every CI run. All register their full declared surface:

Plugin Source Skills Cmds Agents Hooks MCP
plugin-dev claude-plugins-official 7 1 3 — —
pr-review-toolkit claude-plugins-official — 1 6 — —
hookify claude-plugins-official 1 4 1 ✓ —
feature-dev claude-plugins-official — 1 3 — —
security-guidance claude-plugins-official — — — ✓ —
commit-commands claude-plugins-official — 3 — — —
ralph-loop claude-plugins-official — 3 — ✓ —
agent-sdk-dev claude-plugins-official — 1 2 — —
mcp-server-dev claude-plugins-official 3 — — — —
example-plugin claude-plugins-official 2 1 — — ✓
frontend-design claude-plugins-official 1 — — — —
github / context7 / discord external_plugins — — — — ✓
superpowers obra/superpowers 14 3 1 ✓ —
claude-mem thedotmack/claude-mem 5 — — ✓ ✓

See ml_team/tests/test_plugin_marketplace_matrix.py for the CI-run test.

5. Configure shell-command hooks (if your plugin uses them)#

Shell-command hooks (type: command entries in hooks/hooks.json) are disabled by default for security. If your plugin ships them and you want them to run:

swarm features set plugin_shell_hooks_enabled on

What you're consenting to: - Plugin scripts under ${CLAUDE_PLUGIN_ROOT}/ can execute as the swarm API process user - Each invocation is validated against a command allowlist (tools/execution.py) - Each invocation is audited to plugin_shell_executions (SQLite) - Each invocation has a 10-second timeout (configurable, max 60s) - Each invocation gets a scrubbed env with CLAUDE_PLUGIN_ROOT injected

Do not turn this on in production without reading Source code protection first.

6. Uninstall#

swarm plugins uninstall superpowers

This cleans up every surface: - Skill registry: removes all 14 skills - Command registry: removes all 3 commands - Agent registry: removes the sub-agent (namespace plugin-superpowers::*) - Hook registry: removes the hook handler - MCP provider: disconnects any MCP servers (superpowers has none)

Idempotent — safe to re-run.

What's different from Claude Code#

swarm is a superset, not a perfect peer:

CC feature swarm support
.claude-plugin/plugin.json manifest ✅ Full
.mcp.json (MCP servers) ✅ stdio + streamable-HTTP
skills/<name>/SKILL.md ✅ Full
commands/<name>.md ✅ Full + $ARGUMENTS substitution
agents/<name>.md ✅ Full with namespacing (plugin-<plugin>::<agent>)
hooks/hooks.json → type: command ✅ Behind flag + audited
hooks/hooks.json → type: python ✅ Full
hooks/hooks.json → type: http/webhook ⏳ Planned

If you hit a gap, open a GitHub issue — we track it actively.

Publishing your own plugin#

Plugins are directories; publishing is just git push + share a link. No package registry required.

If you want your plugin in our verified-compat matrix, include an entry in your README pointing at this docs page and open a PR against ml_team/tests/test_plugin_marketplace_matrix.py.

Next#