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.
Add a plugin
Section titled “Add a plugin”Use capa add --plugin or edit plugins in the capabilities file.
# Manifest at repo rootcapa add --plugin slackapi/slack-mcp-plugin
# Recursive search by basename / manifest namecapa add --plugin anthropics/claude-code@code-review
# Exact path inside the repocapa add --plugin anthropics/claude-plugins-official::plugins/frontend-design
# Pin a tag or commitcapa add --plugin owner/repo@my-plugin:v1.2.0capa add --plugin owner/repo::plugins/foo#abc1234
# Any git host: clone URL, optional ::subpath and pincapa add --plugin https://git.example.com/team/tools.git::plugins/deploy:v2.0.0capa add --plugin ssh://git@git.example.com/team/tools.gitThen apply:
capa installdef.repo shapes
Section titled “def.repo shapes”| Form | Meaning |
|---|---|
owner/repo | Manifest at the repository root |
owner/repo@basename | Search the repo for a plugin directory basename or manifest name (no slashes in the basename) |
owner/repo::exact/path | Exact 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.1Any git host
Section titled “Any git host”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.0The 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.
Manifest formats
Section titled “Manifest formats”CAPA looks for a manifest in this order:
- Claude:
.claude-plugin/plugin.json - Cursor:
.cursor-plugin/plugin.json - Agent Plugins: a root
plugin.jsonwhose$schemaishttps://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).
Agent Plugins
Section titled “Agent Plugins”An Agent Plugins package contributes only its skills/ folder and the MCP servers in mcp.json. Other folders are ignored.
- Lenient. Problems in
plugin.jsonare install warnings, never failures. A brokenmcp.jsonturns off that plugin’s MCP servers but keeps its skills, and one invalid server entry is skipped while the others load. - Transports.
stdioandstreamable-httpservers are supported.sseservers are skipped with a warning. - Placeholders.
${PLUGIN_ROOT}(the plugin’s installed copy) and${PLUGIN_DATA}(its data folder) are expanded only inargs,envvalues, andcwd. Any other${...}in a server’scommand,args,envvalues, orcwd, and any${at all in itsurlor 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 installremoves it once the plugin is no longer declared, andcapa cleanremoves the project’s plugin data folders.
Remap plugin servers
Section titled “Remap plugin servers”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: slackSkills and tools then reference the stable alias (@slack.…). See Servers and Tools.
Activate what you need
Section titled “Activate what you need”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'