AWS Kiro Custom Subagents Explained: When to Use Them and Why They Matter
Custom Subagents in AWS Kiro are more than just additional AI agents. Learn how they complement Kiro's built-in automation by packaging specialised workflows, tools, permissions, and instructions into reusable capabilities for enterprise software development.
Introduction
When I first read about Custom Subagents in Kiro, I had a simple question.
"Doesn't Kiro already create subagents automatically?"
Whenever I ask Kiro to perform a complex task, it already analyses the repository, gathers context, creates a Spec, executes implementation tasks and even updates documentation. As a developer, I don't have to think about how that work is coordinated.
So why introduce Custom Subagents?
After reading the documentation and experimenting with the feature, I realised they solve a completely different problem.
Custom Subagents aren't about giving Kiro more AI agents. They're about giving engineering teams a way to package specialised workflows, tools, permissions and instructions into reusable capabilities.
Let us look at the difference.
What Kiro Already Does Automatically
Imagine an issue is reported from production:
"Investigate why the Orders API is intermittently returning HTTP 500 errors."
From my perspective, it's a single request.
Behind the scenes, however, Kiro coordinates several activities automatically.
It may:
- analyse the repository
- identify the services involved
- inspect recent code changes
- gather project context
- consult connected MCP tools
- generate an investigation plan
- summarise possible root causes
As developers, we don't manually create separate agents for these activities.
Kiro launches the internal subagents it needs and returns the results.
For most engineering tasks, this works exactly as expected.
So What Are Custom Subagents?
Custom Subagents aren't replacements for Kiro's built-in agents.
Instead, they let you define specialised agents for engineering activities that your team performs repeatedly.
A Custom Subagent can include:
- dedicated instructions
- specific tools
- MCP access
- permissions
- optional Agent Skills
- a defined purpose
Rather than configuring these every time, you define them once and reuse them whenever that type of work is needed.
These aren't temporary workers created for one request.
They're reusable engineering workflows.
Why Not Just Use Steering Files?
This was my next question.
Steering files already capture project conventions, coding standards and architectural guidance.
So where do Custom Subagents fit?
I found it helpful to think of them as solving different problems.
Steering Files answer
"How should software be developed in this repository?"
They provide persistent guidance that Kiro uses across everyday development.
Custom Subagents answer
"How should this specialised engineering activity be performed?"
They package a complete workflow, including tools, permissions and instructions, for a specific task.
In other words, steering files define project guidance, while Custom Subagents define reusable engineering processes
Why Custom Subagents Matter
After reading the Kiro documentation, three capabilities stood out to me.
- Isolated Context
One challenge with AI-assisted development is context management.
Large engineering tasks often involve:
hundreds of files
tool outputs
MCP responses
logs
deployment history
infrastructure configuration
tool outputs
MCP responses
logs
deployment history
infrastructure configuration
If everything is added to one conversation, the context quickly becomes difficult to manage.
Custom Subagents work within their own context window.
Once their task is complete, they return only the information that matters to the main agent.
The benefit isn't more intelligence. It's cleaner, more focused context.
- Reusable Behaviour
Many engineering activities follow the same process every time. Rather than rewriting detailed instructions for each request, a Custom Subagent packages them into a reusable configuration.
According to the Kiro documentation, a Custom Subagent can define
- system instructions
- allowed tools
- MCP access
- model configuration
- permissions
Once created, that workflow can be reused across projects without repeating the same instructions.
- Better Governance
This is the capability that interested me the most.
Different engineering tasks require different permissions.
For example, a documentation subagent might only need:
- Read project files
- Generate Markdown
It doesn't need shell access or AWS credentials.
A deployment-focused subagent might require
AWS access
Terraform
Shell execution
Infrastructure inspection
Instead of giving every AI workflow unrestricted access, each subagent receives only the permissions it needs.
That aligns well with the least-privilege principle many organisations already follow.
Production Readiness Reviews
This is where I think Custom Subagents become particularly useful.
Before every production release, many teams perform a readiness review.
That review typically includes checking
- deployment manifests
- Terraform changes
- IAM policies
- CloudWatch alarms
- backup configuration
- resource tagging
- cost optimisation recommendations
These checks aren't part of normal feature development. They're a specialised engineering workflow.
Instead of describing that workflow every time, a Production Readiness Review subagent can package
- the review instructions
- required AWS tools
- MCP integrations
- reporting format
- permissions
Whenever a release is ready, the same workflow can be executed consistently.
This feels like a much better fit than a steering file because it's a specialised process rather than project-wide guidance.
Architecture Decision Records
Another area where I can see value is generating Architecture Decision Records (ADRs).
Many organisations document important technical decisions before implementing significant architectural changes.
An ADR subagent could:
- analyse the proposed changes
- compare them with the existing architecture
- identify trade-offs
- highlight potential risks
- generate an ADR using the team's standard template
Again, this isn't something needed during everyday coding.
It's a specialised workflow that benefits from being packaged into a reusable subagent.
Where Agent Skills Fit
If you've read my previous article on Kiro Powers, you might wonder where Agent Skills fit into this picture.
I think of them as complementary building blocks.
- Steering Files provide project guidance.
- Agent Skills provide reusable domain knowledge.
- Custom Subagents package specialised workflows, permissions and tools.
Together, they allow Kiro to support much more than code generation.
They help standardise how engineering work is performed.
Final Thoughts
When I first heard about Custom Subagents, I assumed they were simply a way to create more AI agents.
After exploring the feature, I realised that's not their real purpose.
Kiro already creates internal subagents automatically for tasks like repository analysis, context gathering and parallel execution. As developers, we rarely need to think about those.
Custom Subagents address a different need. They let teams package specialised engineering workflows—with their own instructions, tools, permissions and context—into reusable capabilities that can be invoked whenever required.
For me, that's the real value. It's not about adding more AI agents; it's about making repeatable engineering processes more consistent and easier to reuse across projects. As enterprise AI development continues to evolve, I believe capabilities like this will help teams scale their engineering practices, not just their code generation.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article