Subagents allow Kiro to run multiple tasks in parallel, or delegate specific tasks to subagents that specialize in those tasks. Kiro will automatically launch subagents as appropriate. You can also launch subagents manually by instructing Kiro to do so via a prompt such as "Run subagents to...".
Kiro has two built-in subagents: a "context gathering" subagent used to explore a project and gather relevant context, and a "general purpose" subagent used for parallelizing all other tasks.
Subagents run in parallel; however, the main Kiro agent will wait until all subagents have completed before proceeding. Each subagent has its own context window, ensuring that the main agent context is not polluted by the subagent's execution. Subagents automatically return their results back to the main agent once they finish.
Steering files and MCP servers work in subagents exactly as they do in the main agent. However, subagents do not have access to Specs, and Hooks will not trigger in subagents.
You can significantly speed up development by leveraging subagents to perform multiple tasks simultaneously. In the following example, subagents are used to fetch and analyze several tickets in parallel. Not only is this faster than analyzing the tickets sequentially, the tool call and ticket details stay within each subagent and do not pollute the main agent's context.
You can define your own custom agent by creating a markdown (.md) file in ~/.kiro/agents (global) or <workspace>/.kiro/agents (workspace scope). Enter the prompt for the custom agent in the body of the markdown file, and define additional attributes as YAML front matter.
For example, to create a simple "code reviewer" custom agent, create ~/kiro/agents/code-reviewer.md with the following content:
--- name: code-reviewer description: Expert code review assistant. tools: ["read", "@context7"] model: claude-sonnet-4 --- You are a senior code reviewer. ## Your Responsibilities - Review code for correctness, performance, and security ...
When launching subagents, Kiro will automatically select the appropriate custom agent configuration for each subagent, based on the description field. You can also explicitly ask Kiro to use a specific subagent, for example: "Use the code-reviewer subagent to find performance issues in my code".
Below is a list of attributes you can use in the frontmatter. The name attribute is mandatory; all others are optional.
| Attribute | Description | Example value | Default value, if omitted |
|---|---|---|---|
| name | Name of the agent | code-reviewer | Name of the .md file |
| description | Description of the agent | Expert code review assistant | No description |
| tools | List (array) of tools the agent can access | ["@builtin", "@context7"] | No tools |
| model | The model to use | claude-sonnet-4 | LLM currently selected in chat |
| includeMcpJson | If true, then all MCP tools are included | true | false |
| includePowers | If true, then all MCP tools in Powers are included | true | false |
In the tools field, you can use the following:
Wildcarding is supported, e.g., tools: ["*"] to include all built-in and MCP tools, or tools: ["@figma/*"] to include all tools from the figma MCP server.
Subagents