Skills, MCP and plugins

After this page you know the three ways the swarm agent gets capabilities (skills, MCP servers, and plugins), which one your change needs, and how to add it. All of this applies to the swarm agent only; legacy Goose recipes have their own mechanism (ADR 0023).

The three vehicles

• Skills are markdown notes of procedural know-how (SKILL.md files). The model invokes one by name when a task matches its description, and the full body loads into context on demand. Words only, no bundled scripts.
• MCP servers connect a bee to an external system (Hive, Figma). Declared in mcp-servers.json, loaded at boot, merged into every query.
• Plugins are packaged capability bundles the Claude Agent SDK can load. The only plugins in use today are Swarm's own skill directories; third-party plugin packs are deliberately not wired up yet (lowest-priority phase of ADR 0109).

Who may add what

ADR 0109 splits ownership along the trust gradient. Bees run headless with no permission prompts, so anything that grants new reach or touches credentials stays engineer-gated; anything that only adds know-how opens up to staff.

Adding a skill

Two routes, same trust bar (review before activation, audit trail, off-switch):

• PR route. Create swarm-skills/skills/<your-skill-name>/SKILL.md with a description in the frontmatter (plus optional when_to_use triggers) and a markdown body. PR review is the activation gate for this route: the SDK only ever receives an explicit skill allowlist (never skills: "all"), so files that merely exist in a cloned repo can't self-enable. Format details in swarm-skills/README.md.
• Dashboard route. Any staff member drafts a skill via POST /api/skills; an admin approves or disables it. Approved skills load at the next bee boot as a second plugin (swarm-skills-remote). Image-baked skills win name collisions, and disabled takes effect without a deploy.

Browse the current catalogue read-only at /skills on the dashboard. Shipped today: use-hive-context, security-self-review, raise-a-pr, run-e2e-after-pr, use-figma-designs.

Adding an MCP server

Add an entry to mcp-servers.json (engineers only). Each server declares a transport, which is http (default), sse, or stdio for a local subprocess, and its credential by reference, never by value: either tokenEnv (an env var name; the ECS execution role injects the secret at task start, and this is the preferred path) or secretArn (the loader fetches it from AWS Secrets Manager at boot):

{
  "name": "figma",
  "transport": "stdio",
  "command": "${FIGMA_MCP_BIN}",
  "auth": { "kind": "bearer", "tokenEnv": "FIGMA_MCP_TOKEN" },
  "scope": "always"
}

The constraint to design around: bees are headless, so a server must accept a token the bee can read non-interactively. Systems that only offer interactive OAuth are excluded for now.

What ships today

• hive: Swarm's connection to Hive, over HTTPS with a bearer token (the loader hard-rejects plain-HTTP URLs).
• figma: a bundled REST-API MCP server run over stdio with a read-only PAT from a service account (PR #195, ADR 0115). Figma's official MCP server is allowlist-only and can't be used headless. ADR 0115 records why, so don't build an OAuth broker expecting it to unlock Figma.
• In-process tools in swarm-agent/tools/: dispatchBee, approval gates, asking the operator for input, thread replies, E2E triggering, web-UI verification. These are code, added by engineers like any other change.

Atlassian is not in the manifest yet; when needed it's a config-only addition, since Atlassian's remote MCP supports headless API-token auth (noted in ADR 0115).

See it in action

The skills catalogue: draft a skill, an admin approves it, and the agent can use it.