Skip to content

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
`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
`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.

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

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.