This article is a machine translation of the contents of the following URL, which I wrote in Japanese:
https://qiita.com/Nana_777/items/c63d0734542981a89672
Introduction
Custom Subagents were implemented in Kiro's IDE on February 5, 2026.
By utilizing custom subagents, you can define and execute routine tasks in parallel.
This article explains how to use Custom Subagents.
Conclusion
- Custom subagents can execute arbitrarily defined tasks.
- Useful for automating repetitive tasks.
- Multiple custom subagents can be executed in parallel.
- Detailed definition and accuracy verification are required to ensure custom subagents function as expected.
- In this test, some unexpected results were observed with the custom subagent.
- Content that is not specified in detail is determined by the AI, resulting in results that are unexpected.
- Too much detail can lead to overloading the context window and making maintenance difficult.
Subagents
When executing multiple tasks, multiple subagents can execute tasks in parallel under instructions from Kiro's main agent.
For example, if multiple issues are registered on GitHub, the main agent can be asked to retrieve the issues and execute tasks using multiple subagents. The multiple subagents will then share the tasks.
This reduces the overall time it takes to complete tasks.
↓ Subagent Image
Custom Subagent
The February 5, 2026, update to Kiro implemented the custom subagent feature.
As the name suggests, custom subagents allow you to predefine the tasks to be performed by the subagent (which tools to use and how to execute them).
Custom Subagent Use Cases
When using custom subagents, it's useful to define tasks that are "repeated," "have a set procedure," and "have complex assumptions, constraints, and procedures."
For example, a custom subagent that reviews code using the same tool, with the same criteria and emphasizing the same perspectives, or a custom test execution subagent that outputs results according to a format specified by a human each time, would be effective.
Illustration of the Difference Between Custom Agents and Skills
A similar feature is AgentSkills, but AgentSkills are like a collection of functions that extend the main agent. The PDF-related SKILL.md file introduced last time defines a set of PDF-related functions such as "Create PDF," "Merge PDF," and "Split PDF."
In contrast, custom agents define the details of a single task, such as a review task, including which tools (MCP or Skills) to use, the steps to take, and what to pay attention to when executing the task.
Previous AgentSkills article
https://qiita.com/Nana_777/items/4d05e92622f928481e29
↓ Illustration of the difference between custom agents and Skills
In the diagram above, Skills is like a carpentry manual that describes how to make chairs, desks, and other items. Custom subagents are like specialized craftsmen who make chairs and desks.
Custom Subagent Definition
You can define custom subagents by chatting with Kiro.
There is no strict formatting other than the attribute, but you can generally define the following:
Attribute
name
Required. This is the agent's unique identifier, and the custom subagent will be called by this name.
As such, it must be unique among other agents.
Only lowercase letters and hyphens are allowed.
description
Required. This is a short sentence (one or two lines) that describes the agent's role and function. If you want to target any languages, specify this here.
tools
Specify the rule categories the agent can use.
Categories include the following:
- read: Read a file
- write: Write a file
- shell: Execute a shell command
- web: Web search
- spec: Spec file operations (only valid in spec mode)
- includeMcpJson: If true, include all MCP tools.
- @ < mcp_server>: Include all tools from a specific MCP server.
- @ < mcp_server>/< tool>: Include a specific tool from a specific MCP server. For other tool definitions, refer to the Kiro documentation.
model
Optional. Specify a model ID if you want to use a specific AI model.
If not specified, the default model (the model used when calling the custom subagent) will be used.
For example, define the attribute as follows:
---
name: cdk-code-reviewer
description: "An agent that performs detailed reviews of AWS CDK code from the perspectives of best practices, security, cost optimization, and performance. It provides assessments based on the Well-Architected Framework and specific improvement suggestions in Japanese."
tools: ["read", "write"]
---
Agent Roles and Responsibilities
Describe the subagent's roles and tasks.
This section will overlap with the description and procedures listed in the Attributes, but it should provide a list of the tasks the subagent will perform without providing detailed instructions.
## AWS CDK Code Review Agent
You are an expert agent specializing in AWS CDK (Cloud Development Kit) code reviews.
### Roles and Responsibilities
1. **Security** - Evaluate based on the security pillar of the AWS Well-Architected Framework
2. **Cost Optimization** - Reduce unnecessary costs and recommend efficient resource utilization
3. **Performance** - Ensure optimal resource configuration and scalability
4. **Reliability** - Evaluate high availability, disaster recovery, and backup strategies
5. **Operational Excellence** - Review monitoring, logging, and deployment strategies
6. **Best Practices** - CDK-specific recommended patterns and naming conventions
About Tools Used (MCP, Powers, Skills, etc.)
When calling tools external to Kiro, define the tool name and its purpose as follows:
### Available Tools
#### AWS Infrastructure as Code Power
Use the following tools during your review:
1. **cdk_best_practices** - Get the CDK Best Practices Guide
- Be sure to do this at the start of your review
- Refer to the latest security guidelines, architecture patterns, and development workflows
2. **search_cdk_documentation** - Search the official CDK documentation
- Verify the correct usage of specific constructs
- Research recommended settings for properties and methods
3. **search_cdk_samples_and_constructs** - Search CDK code samples
- See implementation examples following best practices
- Check for language-specific idioms
4. **validate_cloudformation_template** - Validate a CloudFormation template
- Check the syntax of templates synthesized with CDK code
- Validate resource properties
5. **check_cloudformation_template_compliance** - Check security compliance
- Ensure compliance with AWS Control Tower proactive controls
- Detecting Violations of Security Best Practices
Task Execution Procedure
Enter the title and details of each step to perform the task.
Details include which tools will be used and which commands will be executed.
For example, define it as follows:
### Review Process
#### 1. Code Analysis
(Details of the procedure, what to consider during this step)
#### 2. Security Check
(Details of the procedure, what to consider during this step)
#### 3. Cost Optimization Check
(Details of the procedure, what to consider during this step)
#### 4. Performance Check
(Details of the procedure, what to consider during this step)
#### 5. Best Practice Check
(Details of the procedure, what to consider during this step)
Output Format
In what language? In what format, such as Markdown?
If the output format is fixed and you want to assign values, define it by enclosing it in "
```" as follows:
## AWS CDK Code Review Results
### Summary
- Review Target: [File/Directory Name]
- Issues Found: Critical: X, High: Y, Medium: Z, Low: W
- Overall Rating: [Excellent/Good/Needs Improvement/Severe Issues]
### Critical (Severe)
#### [Issue Title]
**Location**: `File Name:Line Number`
**Problem**: [Specific Problem Description]
**Risk**: [Security Risk, Cost Impact, Performance Impact, etc.]
**Recommended Action**: [Specific Fix]
Error Handling
Define the desired behavior when an error occurs during execution of a custom subagent.
For example, define it as follows:
### Error Handling
- Detailed analysis of error messages when test execution fails
- Suggests running `npm install` if there are dependency issues
- Identifies stack definition issues when CDK synth fails
- Suggests test optimization when a timeout error occurs
Usage Examples
Define usage examples when using a custom subagent that generates multiple documents, such as when you want to generate only some of the documents.
Define it as follows:
### Usage Example
If a user requests "Generate project documentation":
1. Analyze the project structure
2. Read key files
3. Generate a comprehensive set of documentation
4. Report an overview of the generated documentation
If a user requests "Generate only API documentation":
1. Identify the public API
2. Analyze the details of each API element
3. Generate API.md
4. Report the generated documentation
Verifying the operation of a custom subagent
Creating a custom subagent
As an example, we created three agents: a "CDK code review agent," a "documentation generation agent," and a "test execution agent."
Requesting parallel execution
To run the subagents we created in parallel, we send a chat request saying, "Please generate documentation, review CDK code, and run tests. If possible, please run them in parallel."
↓ We were able to confirm that the custom subagents were running in parallel.
Execution Results
The following results were confirmed after the custom subagents were executed.
The code review executed the defined tasks and output the results in the specified format.
↓ Specifying the output format for code review results
↓ Actual output results
The test execution custom subagent does not handle undefined errors.
The test execution custom subagent executed the tests and output the results as defined.
However, test coverage was determined to be 0% due to a problem with the Jest configuration.
This is likely because the custom subagent has not defined any behavior to correct issues when coverage values are inaccurate due to insufficient configuration.
If you want the configuration to be corrected when a problem occurs, you will need to explicitly define in the custom subagent which issues the corrections should be made when they occur.
Project documentation generation also generated documentation other than what was defined.
The custom documentation generation subagent defines the following files, as shown in the screenshot below:
README.md: Project overview, installation, and quick start
API.md: Detailed API specifications and references
ARCHITECTURE.md: System architecture and design philosophy
USAGE.md: Detailed usage instructions and sample code
CONTRIBUTING.md: Developer guide (if necessary)
Five types of files were defined.
As shown in the screenshot below, nine files were actually generated, including "PROJECT_OVERVIEW.md," which contains the project summary that should have been included in the README.
This result appears to be an autonomous decision made by the custom subagent based on the following criteria:
- Agent Autonomous Decision-Making: Determine an appropriate structure for the project's scale.
- Readability Considerations: Keep README.md concise.
- Separation of Concerns: Separate information for different purposes into different files.
- Best Practices: Follow industry standards for document structure.
If you want to prevent such autonomous decision-making by the agent, you need to define stronger behavioral restrictions, such as "Create only defined files, and do not create any other files."
Conclusion
Custom subagents can execute multiple tasks in a predefined sequence and can even execute multiple subagents in parallel.
Automatically executing multiple tasks with a predefined sequence in parallel improves development efficiency.
Verifying the granularity of the definition and the accuracy of the results is necessary to ensure that custom subagents work as expected.
In this testing, we observed unexpected issues not being automatically fixed, resulting in 0% test coverage, and unexpected files being generated when generating documentation.
To ensure that custom subagents work as expected, more detailed and specific definitions are required. However, providing too much detail can constrict the context window and result in incomplete results.
It is necessary to carefully review the AI's output and have repeated discussions with the AI to improve the accuracy of custom subagents.
Top comments (0)