Skip to content

Plugins

Plugins are remote packages (type: github, gitlab, or git) that ship a provider-style manifest. On install, CAPA unpacks the pieces you care about (skills, servers, tools, rules, hooks, and sub-agents) into the CAPA model rather than dropping a opaque plugin folder into every client.

Plugin-owned entries can appear locked in the Web UI so you do not casually edit or reorder what the plugin owns.

Unpacked rules, hooks, and sub-agents go through the normal install steps, so the same rules apply as for entries you declare yourself: rule placement and conflict reporting, sub-agent provider targeting, and surgical capa:<id> hook entries.

Use capa add --plugin or edit plugins in the capabilities file.

Terminal window
# Manifest at repo root
capa add --plugin slackapi/slack-mcp-plugin
# Recursive search by basename / manifest name
capa add --plugin anthropics/claude-code@code-review
# Exact path inside the repo
capa add --plugin anthropics/claude-plugins-official::plugins/frontend-design
# Pin a tag or commit
capa add --plugin owner/repo@my-plugin:v1.2.0
capa add --plugin owner/repo::plugins/foo#abc1234
# Any git host: clone URL, optional ::subpath and pin
capa add --plugin https://git.example.com/team/tools.git::plugins/deploy:v2.0.0
capa add --plugin ssh://git@git.example.com/team/tools.git

Then apply:

Terminal window
capa install
FormMeaning
owner/repoManifest at the repository root
owner/repo@basenameSearch the repo for a plugin directory basename or manifest name (no slashes in the basename)
owner/repo::exact/pathExact subpath from the repo root

GitLab nested groups work the same way (group/sub/project@name or ::path). Optional pinning uses :tag / :branch or #sha (stored as def.version / def.ref when added via the CLI).

plugins:
- id: frontend-design
type: github
def:
repo: anthropics/claude-plugins-official::plugins/frontend-design
- id: devops-skills
type: gitlab
def:
repo: acme/platform/team/services/devops-skills
version: v1.0.1

type: git takes the clone URL in def.url instead of def.repo, plus an optional def.subpath for a plugin that is not at the repo root, and def.version / def.ref to pin:

plugins:
- id: deploy-tools
type: git
def:
url: https://git.example.com/team/tools.git
subpath: plugins/deploy
version: v2.0.0

The same rules apply as for type: git skills: https://, ssh://, and file:// URLs (plain http:// only for localhost), the newest vX.Y.Z tag when unpinned, private repos through your git credential helper or SSH key, and user:token@ in the URL never written to capabilities.yaml or the lockfile.

CAPA looks for a manifest in this order:

  1. Claude: .claude-plugin/plugin.json
  2. Cursor: .cursor-plugin/plugin.json
  3. Agent Plugins: a root plugin.json whose $schema is https://agent-plugins.org/schemas/1.0.0/plugin.schema.json

With no manifest, CAPA still scans the usual folders (skills/, commands/, agents/, hooks/, rules/, .mcp.json).

An Agent Plugins package contributes only its skills/ folder and the MCP servers in mcp.json. Other folders are ignored.

  • Lenient. Problems in plugin.json are install warnings, never failures. A broken mcp.json turns off that plugin’s MCP servers but keeps its skills, and one invalid server entry is skipped while the others load.
  • Transports. stdio and streamable-http servers are supported. sse servers are skipped with a warning.
  • Placeholders. ${PLUGIN_ROOT} (the plugin’s installed copy) and ${PLUGIN_DATA} (its data folder) are expanded only in args, env values, and cwd. Any other ${...} in a server’s command, args, env values, or cwd, and any ${ at all in its url or headers, makes CAPA skip that server with a warning. This keeps a plugin from pulling your stored secrets or environment variables into its requests.
  • Data folder. ${PLUGIN_DATA} is ~/.capa/plugin-data/<projectId>/<slug>-<hash>/, keyed by where the plugin comes from rather than by its own name. It survives plugin updates; capa install removes it once the plugin is no longer declared, and capa clean removes the project’s plugin data folders.

If a plugin declares MCP servers under names that collide with yours, remap them with plugins[].servers:

plugins:
- id: slack-plugin
type: github
def:
repo: slackapi/slack-mcp-plugin
servers:
slack-server:
as: slack

Skills and tools then reference the stable alias (@slack.…). See Servers and Tools.

Unpacking alone does not expose every plugin tool or skill. Declare the tools you want under top-level tools, and activate plugin skills with type: plugin (or bind tools via requires on other skills). CAPA warns at install if a type: plugin skill id does not match a skill from any configured plugin manifest.

skills:
- id: frontend-design
type: plugin
def:
requires:
- '@some-server.tool_id'