Sub-Agents

The subagents section of your capabilities file lets you define named sub-agents — each with a filtered MCP endpoint that exposes only its declared tools, plus provider-native agent definition files for Claude Code and Cursor.

Use sub-agents to divide a large project between specialists. An infra-agent can be limited to CDK and Terraform tools while an api-agent only sees Lambda and logging tools — even though both connect through the same CAPA server.

How It Works

On capa install, each sub-agent entry produces:

Provider MCP registration Agent definition file
claude-code .mcp.json → key capa-{id} .claude/agents/{id}.md + CLAUDE.md context block
cursor Main capa entry only (no separate MCP key) .cursor/agents/{id}.md

The filtered MCP endpoint at /{projectId}/agents/{id}/mcp exposes only the tools declared in that sub-agent's tools list. Calls to any other tool are rejected with a clear error. Cursor reads the description field in .cursor/agents/*.md to automatically delegate tasks — no separate MCP entry per sub-agent is needed.

Configuration

subagents:
  - id: infra-agent
    description: AWS CDK and Terraform specialist. Use when working in backend-infra/ or user-infra/.
    skills:
      - my-iac-skill          # skill IDs from the top-level skills array
    tools:
      - search_cdk_docs       # tool IDs from the top-level tools array
      - validate_cfn
      - check_cfn_compliance
    instructions: |
      You are the infra-agent — an AWS CDK infrastructure specialist.

      ## Scope
      Work exclusively in backend-infra/ and user-infra/.

      ## Rules
      - Always prefer CDK L2 constructs over L1 (Cfn*)
      - Run validate_cfn before recommending any cdk deploy

  - id: api-agent
    description: Python Lambda and FastAPI specialist. Use for Lambda function work.
    skills:
      - my-serverless-skill
    tools:
      - get_lambda_guidance
      - sam_logs
      - get_metrics
    instructions: |
      You are the api-agent — a Python Lambda and FastAPI specialist.

      ## Scope
      Work exclusively on Lambda functions in backend-api-handler/ and chat-handler/.
{
  "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", "check_cfn_compliance"],
      "instructions": "You are the infra-agent..."
    },
    {
      "id": "api-agent",
      "description": "Python Lambda and FastAPI specialist. Use for Lambda function work.",
      "skills": ["my-serverless-skill"],
      "tools": ["get_lambda_guidance", "sam_logs", "get_metrics"],
      "instructions": "You are the api-agent..."
    }
  ]
}

Fields

Field Required Description
id Yes Unique identifier. Used as the MCP key (capa-{id}) and agent file name ({id}.md).
description No Role description. For Cursor, this drives automatic delegation — be specific about when to use this agent.
skills Yes List of skill IDs from the top-level skills array. Listed in the generated agent files for context.
tools Yes List of tool IDs from the top-level tools array. Only these tools are exposed on the agent's filtered MCP endpoint.
instructions No Markdown text appended to the agent file body. Use for role-specific rules, scope constraints, or conventions.

Generated Files

Claude Code — .claude/agents/{id}.md

Claude Code reads .claude/agents/ as sub-agent definitions. CAPA writes each file with the standard frontmatter Claude Code expects:

---
name: infra-agent
description: AWS CDK and Terraform specialist. Use when working in backend-infra/ or user-infra/.
model: inherit
---
**MCP server key:** `capa-infra-agent`
**Skills:** my-iac-skill
**Tools:** aws-iac.search_cdk_docs, aws-iac.validate_cfn, aws-iac.check_cfn_compliance

You are the infra-agent — an AWS CDK infrastructure specialist.

## Scope
Work exclusively in backend-infra/ and user-infra/.

A CLAUDE.md context block is also upserted so the main agent is aware of available sub-agents.

Cursor — .cursor/agents/{id}.md

Cursor reads .cursor/agents/*.md for sub-agent definitions. CAPA writes the format Cursor expects, including the readonly and is_background frontmatter fields:

---
name: infra-agent
description: AWS CDK and Terraform specialist. Use when working in backend-infra/ or user-infra/.
model: inherit
readonly: false
is_background: false
---
**MCP server key:** `capa-infra-agent`
**Skills:** my-iac-skill
**Tools:** aws-iac.search_cdk_docs, aws-iac.validate_cfn, aws-iac.check_cfn_compliance

You are the infra-agent — an AWS CDK infrastructure specialist.

Cursor uses the description field to decide when to automatically delegate tasks to this sub-agent — write it as a clear trigger condition.

Tool Filtering

The filtered MCP endpoint enforces the tools list strictly:

  • tools/list: only returns tools declared in the sub-agent's tools list, resolved to their qualified names (e.g. aws-iac.search_cdk_docs).
  • tools/call: rejects any call to a tool not in the sub-agent's allowed set with a clear JSON-RPC error.

Tool IDs in tools reference the id field from the top-level tools array — not the underlying MCP tool name. CAPA resolves them to qualified names automatically.

Cleanup

  • On each capa install: sub-agents removed from the config are automatically unregistered and their agent files deleted.
  • capa clean: removes all sub-agent MCP registrations and agent files.

Full Example

providers:
  - claude-code
  - cursor

skills:
  - id: iac-skill
    type: github
    def:
      repo: my-org/skills@iac

  - id: serverless-skill
    type: github
    def:
      repo: my-org/skills@serverless

servers:
  - id: aws-iac
    type: mcp
    def:
      cmd: uvx
      args: [awslabs.aws-iac-mcp-server@latest]

  - id: aws-serverless
    type: mcp
    def:
      cmd: uvx
      args: [awslabs.aws-serverless-mcp-server@latest]

tools:
  - id: search_cdk_docs
    type: mcp
    def:
      server: "@aws-iac"
      tool: search_cdk_documentation

  - id: validate_cfn
    type: mcp
    def:
      server: "@aws-iac"
      tool: validate_cloudformation_template

  - id: get_lambda_guidance
    type: mcp
    def:
      server: "@aws-serverless"
      tool: get_lambda_guidance

  - id: sam_logs
    type: mcp
    def:
      server: "@aws-serverless"
      tool: sam_logs

subagents:
  - id: infra-agent
    description: AWS CDK and Terraform specialist. Use when working in infrastructure repos.
    skills:
      - iac-skill
    tools:
      - search_cdk_docs
      - validate_cfn
    instructions: |
      You are the infra-agent. Work exclusively in backend-infra/ and user-infra/.
      Always prefer CDK L2 constructs over L1 (Cfn*).

  - id: api-agent
    description: Python Lambda specialist. Use for Lambda function work.
    skills:
      - serverless-skill
    tools:
      - get_lambda_guidance
      - sam_logs
    instructions: |
      You are the api-agent. Work exclusively on Lambda functions.
      Always use Lambda Powertools Logger for structured logging.
{
  "providers": ["claude-code", "cursor"],
  "skills": [
    { "id": "iac-skill", "type": "github", "def": { "repo": "my-org/skills@iac" } },
    { "id": "serverless-skill", "type": "github", "def": { "repo": "my-org/skills@serverless" } }
  ],
  "servers": [
    { "id": "aws-iac", "type": "mcp", "def": { "cmd": "uvx", "args": ["awslabs.aws-iac-mcp-server@latest"] } },
    { "id": "aws-serverless", "type": "mcp", "def": { "cmd": "uvx", "args": ["awslabs.aws-serverless-mcp-server@latest"] } }
  ],
  "tools": [
    { "id": "search_cdk_docs", "type": "mcp", "def": { "server": "@aws-iac", "tool": "search_cdk_documentation" } },
    { "id": "validate_cfn", "type": "mcp", "def": { "server": "@aws-iac", "tool": "validate_cloudformation_template" } },
    { "id": "get_lambda_guidance", "type": "mcp", "def": { "server": "@aws-serverless", "tool": "get_lambda_guidance" } },
    { "id": "sam_logs", "type": "mcp", "def": { "server": "@aws-serverless", "tool": "sam_logs" } }
  ],
  "subagents": [
    {
      "id": "infra-agent",
      "description": "AWS CDK and Terraform specialist. Use when working in infrastructure repos.",
      "skills": ["iac-skill"],
      "tools": ["search_cdk_docs", "validate_cfn"],
      "instructions": "You are the infra-agent. Work exclusively in backend-infra/ and user-infra/."
    },
    {
      "id": "api-agent",
      "description": "Python Lambda specialist. Use for Lambda function work.",
      "skills": ["serverless-skill"],
      "tools": ["get_lambda_guidance", "sam_logs"],
      "instructions": "You are the api-agent. Work exclusively on Lambda functions."
    }
  ]
}

Related Documentation