Sub-agents

Sub-agents are named specialist configurations. You declare them under subagents; capa install writes provider agent files and, where supported, wires a filtered MCP endpoint that exposes only the tools you list.

Declare a sub-agent

Field	Required	Purpose
`id`	yes	MCP key stem (`capa-{id}`) and agent filename
`providers`	no	Allow-list of provider ids to generate this sub-agent for; omit (or `[]`) for every active provider
`description`	no	Role text, especially important for Cursor auto-delegation
`skills`	yes	Skill ids from the top-level `skills` array
`tools`	yes	Tool ids from the top-level `tools` array
`nativeTools`	no	Provider-native tool names (`Read`, `Bash`): a different namespace from `tools`
`model`	no	Model this agent runs on, in the provider’s own vocabulary
`instructions`	no	Extra markdown appended to the agent file body

subagents:
  - id: infra-agent
    description: AWS CDK and Terraform specialist. Use when working in backend-infra/ or user-infra/.
    skills:
      - my-iac-skill
    tools:
      - search_cdk_docs
      - validate_cfn
    instructions: |
      You are the infra-agent. Work exclusively in backend-infra/ and user-infra/.

Skill and tool ids must already exist in the capabilities file. See Skills and Tools.

`tools` vs `nativeTools`

These are two different namespaces and both can be set on one agent:

tools: capa tool ids. Defines the agent’s filtered capa-{id} MCP endpoint.
nativeTools: the provider’s own tool names, written into the agent file as an allow-list where the provider has one. Claude Code’s tools: frontmatter is such a list, and omitting it lets the agent inherit every tool. capa appends mcp__capa-{id} to whatever you list, so restricting native tools never cuts the agent off from its own endpoint.

Omitting nativeTools inherits the provider’s tools; nativeTools: [] is an explicit restriction to the agent’s capa tools alone.

subagents:
  - id: ci-watcher
    description: Watches a CI job and reports failures. Observes only.
    skills: []
    tools:
      - fetch_job_log
    nativeTools: [Read, Grep, Glob, Bash]
    model: haiku

nativeTools and model are written in one provider’s vocabulary: haiku means nothing to Cursor, whose model takes ids like composer-2, and whose agent files have no tool allow-list at all. capa only emits them for providers that use the same vocabulary. Values you author here are taken at face value; values unpacked from a plugin travel only to the provider family the plugin was written for.

From plugin agents

Plugin agent markdown maps onto these fields: name → id, description, skills, tools → nativeTools, and model. Any other frontmatter key (color, for instance) has no capa equivalent and is reported during install.

Target specific providers

By default capa generates each sub-agent for every active provider that supports sub-agents. Use providers to limit it, useful in multi-provider repos where an agent only makes sense for one client:

providers: [claude-code, cursor, codex]

subagents:
  - id: infra-agent
    providers: [claude-code]   # no .cursor/agents or .codex/agents file
    skills: [my-iac-skill]
    tools: [search_cdk_docs]

Unknown provider ids fail validation.
Listed providers that aren’t active for this install are ignored; if none are active, capa warns and skips the sub-agent.
Active providers without sub-agent support get a warning and are skipped.
When you retarget a sub-agent (or run capa clean), capa removes only the agent files and MCP entries it generated. A same-name file or entry you replaced by hand is left alone.

providers is honored by managed installs, --passthrough, plugin-sourced sub-agents, and the Web UI editor.

Cursor vs Claude Code

Provider	MCP	Agent file
`claude-code`	Registers `capa-{id}` pointing at the filtered agent MCP endpoint; also notes the agent in `CLAUDE.md`	`.claude/agents/{id}.md`
`cursor`	Keeps the main `capa` MCP entry only (no per-sub-agent MCP key)	`.cursor/agents/{id}.md`: Cursor uses `description` to decide when to delegate

Other providers with a sub-agent convention get their own agent files too: for example Codex (.codex/agents/{id}.toml), Gemini CLI (.gemini/agents/{id}.md), OpenCode (.opencode/agents/{id}.md), and GitHub Copilot (.github/agents/{id}.md).

The filtered endpoint (/{projectId}/agents/{id}/mcp) allows only the tools listed on that sub-agent. Other tool calls are rejected with a clear error.

Under toolExposure: none, capa still writes sub-agent instruction files for documentation, but does not register project-local MCP entries for them.

Cleanup

Removing a sub-agent from the file and re-running install unregisters it and deletes its agent files. capa clean removes all capa-managed sub-agent registrations.