Skip to content
CAPA CAPA CAPA Docs

Plugins

Plugins are remote packages (type: github or gitlab) 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.

Add a plugin

Section titled “Add a plugin”

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

Then apply:

Terminal window
capa install

def.repo shapes

Section titled “def.repo shapes”
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

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: slack

Skills 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'
Section titled “Related”