Lesson 9

Custom Agents

What Custom Agents Are

A custom agent is a specialised version of Kiro with its own system prompt, tool access, and optionally its own MCP servers. You define it in a config file, and Kiro can spawn it as a sub-agent when the task matches its description - or you can invoke it explicitly.

Think of it as: a sub-agent with a personality and toolbox you've defined in advance.

Where Custom Agents Live

Same two-scope pattern as steering and skills.

The Agent File Format (IDE)

In the IDE, a custom agent is a markdown file with YAML front-matter. The body is the agent's system prompt - the instructions it follows when spawned.

---
name: frontend-agent
description: Specialist in Angular components, templates, and browser tooling
model: auto
tools:
  - read_file
  - fs_write
  - str_replace
  - execute_bash
  - grep_search
mcpServers:
  - component-docs
---

You are a frontend specialist working on an Angular 18 application.

## Your expertise
- Angular standalone components with signals
- RxJS for async data streams
- Template syntax and change detection
- SCSS styling with our design token system

## Rules
- Always create standalone components
- Use inject() over constructor injection
- Prefer signals over BehaviorSubject for new code
- Run ng lint after changes

Front-matter Schema (IDE)

If you omit tools, the agent gets all tools. If you specify it, the agent is restricted to only those tools - useful for creating read-only agents or agents that can't run shell commands.

How Custom Agents Get Used

Automatic selection

Kiro reads the description of all available custom agents. When a task matches, it spawns the appropriate agent as a sub-agent. For example, if you ask "update the header component's styling" and you have a frontend-agent with a matching description, Kiro may choose to delegate to it.

Explicit invocation

You can name the agent directly: "Use the frontend-agent to refactor this component" or "Run the docs-agent on this file."

How is this different from asking a skill to run in parallel?

Both can run in parallel - the difference is about constraints and identity, not concurrency:

A skill is instructions anyone can follow. A custom agent is a specific person with defined capabilities and limits.

Practical Examples

Read-only research agent

---
description: Research and analyse code without making changes
tools:
  - read_file
  - grep_search
  - file_search
  - list_directory
---

You are a research assistant. Your job is to explore the codebase and
provide analysis. You cannot modify any files or run commands.

When asked to investigate something:
1. Search for relevant files
2. Read and understand the code
3. Provide a clear summary of findings
4. Suggest next steps (but don't implement them)

Test writer agent

---
description: Write and run unit tests for Angular components and services
tools:
  - read_file
  - fs_write
  - str_replace
  - execute_bash
  - grep_search
---

You are a testing specialist for an Angular application using Jest.

## Rules
- Every test file lives next to its source: `foo.component.spec.ts`
- Use Testing Library for component tests
- Mock HTTP calls with HttpClientTestingModule
- Run tests after writing: `npx jest --testPathPattern=<file>`
- Aim for meaningful assertions, not just coverage

Backend API agent

---
description: Work with the Node.js/Express API layer and database
tools:
  - read_file
  - fs_write
  - str_replace
  - execute_bash
  - grep_search
mcpServers:
  - postgres
---

You are a backend specialist working on the Express API.

## Your domain
- Routes in src/api/
- Services in src/services/
- Database access via the postgres MCP server

## Rules
- All endpoints validate input with zod
- Use parameterised queries (never string interpolation)
- Return consistent error responses: { error: string, code: number }

When and Why: Custom Agents vs. Just Asking Kiro

You might think: "Why not just ask Kiro to do this in the main conversation, or use a skill?" Here's when a custom agent genuinely adds value over alternatives:

Use a custom agent when you need:

Just use a skill (or ask Kiro directly) when:

• You need the task done in the current context (not isolated)
• You don't need to restrict tools - the main agent's full toolbox is fine
• The task is straightforward and doesn't need a different model
• You want to see everything happen step-by-step in the main conversation

Concrete comparison

Scenario: "Lint all components and fix issues"

• Skill approach: A skill provides instructions on how to lint. Kiro follows them in the main context. Every file read and fix happens in your main conversation's token budget. Fine for a few files.
• Sub-agent approach: "Use subagents to lint these files in parallel." Kiro spawns general-purpose sub-agents. Faster, isolated context, but they have full tool access - could theoretically do anything.
• Custom agent approach: You have a lint-agent.md that only has read_file, str_replace, and execute_bash (scoped to ng lint). It can't accidentally delete files, can't run arbitrary commands, can't access your database MCP server. Safest option for delegating to run autonomously.

Scenario: "Research how auth works in this codebase"

• Main agent: Reads 15 files directly in your conversation - uses all your context budget.
• Built-in context gatherer: Does the same exploration in an isolated context, returns a summary. Good, but it uses all tools and has no domain-specific instructions.
• Custom research agent: Read-only tools only (can't modify anything), has your project-specific instructions baked in ("auth uses JWT tokens stored in HttpOnly cookies, check src/auth/"). Safer, more focused, returns better results because it has domain context from its prompt.

Tool restriction is a safety and focus mechanism:

• Read-only agents - can explore but not break anything (remove write/bash tools)
• Focused agents - a docs agent doesn't need bash access; a test agent doesn't need web tools
• Security - limit what a sub-agent can do to reduce blast radius

Custom Agents vs Skills

The CLI Difference

In the Kiro CLI, custom agents use a more elaborate YAML/JSON config format (not markdown) and support additional features like:

• allowedTools - tools that can run without asking for permission
• toolAliases - renaming tools to avoid collisions
• includeMcpJson - whether to inherit mcp.json servers
• resources - files pre-loaded into context
• hooks - agent-specific hooks

The IDE format (markdown with front-matter) is simpler but covers the common cases. If you move to the CLI for more advanced workflows, the config options expand significantly. See CLI Agent Config Reference for the full schema.

Your Tangible Win

You can now create custom agents with scoped tools, specific MCP access, and focused system prompts. You know how they differ from skills (isolated context, tool restriction, MCP scoping), how Kiro auto-selects them, and how to invoke them explicitly. You can build a team of specialised agents for your project.

Quiz