Sub-Agents

What's Changed

New Feature: Sub-Agents

Define named sub-agents in your capabilities.yaml — each with a filtered MCP endpoint that exposes only its declared tools, plus provider-native agent definition files for Claude Code and Cursor.

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: |
      Work exclusively in backend-infra/ and user-infra/.

  - id: api-agent
    description: Python Lambda specialist. Use for Lambda function work.
    skills:
      - my-serverless-skill
    tools:
      - get_lambda_guidance
      - sam_logs

How it works

• Filtered MCP endpoint at /{projectId}/agents/{id}/mcp — exposes only the tools declared in tools. Unauthorized tools/call requests are rejected with a clear error.
• Claude Code (claude-code provider): writes .claude/agents/{id}.md with name/description/model: inherit frontmatter + upserts a context block in CLAUDE.md. Registers capa-{id} in .mcp.json pointing at the filtered endpoint.
• Cursor (cursor provider): writes .cursor/agents/{id}.md with name/description/model/readonly/is_background frontmatter. Cursor auto-delegates based on the description field — no separate MCP entry per sub-agent is needed.
• Cleanup: sub-agents removed from the config are automatically unregistered on the next capa install. capa clean removes all sub-agent registrations and agent files.

subagents fields

Field	Required	Description
id	Yes	Unique identifier. Used as the MCP key (capa-{id}) and agent file name.
description	No	Role description. For Cursor, drives automatic delegation — be specific.
skills	Yes	Skill IDs from the top-level skills array.
tools	Yes	Tool IDs from the top-level tools array. Only these are exposed on the filtered endpoint.
instructions	No	Markdown content appended to the agent file body.

See the Sub-Agents documentation for the full reference. (#35)

Full Changelog: v1.2.5...v1.3.0