Custom agents allow you to tailor Kiro behavior for specific tasks by defining which tools are available, what permissions are granted, and what context is automatically included.
Create an agent file directly in your project:
.kiro/agents/ directory in your workspace (or ~/.kiro/agents/ for global agents)For example, create .kiro/agents/backend-dev.md:
--- name: backend-dev description: Backend development specialist model: claude-sonnet-4 tools: ["read", "write", "shell"] permissions: rules: - capability: shell match: ["npm *", "git *"] effect: allow --- You are a backend engineer focused on Node.js and TypeScript. Always use async/await. All database queries must be parameterized.
Then switch to it using the agent picker in the chat pane header.
Custom agents are defined using JSON configuration files. Here's a basic example:
{ "name": "my-agent", "description": "A custom agent for my workflow", "tools": ["read", "write"], "allowedTools": ["read"], "resources": [ "file://README.md", "file://.kiro/steering/**/*.md", "skill://.kiro/skills/**/SKILL.md" ], "prompt": "You are a helpful coding assistant", "model": "claude-sonnet-4" }
See the Configuration reference for full details on all available fields.
You can define local agents and global agents.
.kiro/agents/
Local agents are specific to the current workspace and only available when running Kiro from that directory or its subdirectories.
Example:
my-project/ ├── .kiro/ │ └── agents/ │ ├── dev-agent.json │ └── aws-specialist.json └── src/ └── main.py
~/.kiro/agents/
Global agents are available from any directory.
Example:
~/.kiro/agents/ ├── general-assistant.json ├── code-reviewer.json └── documentation-writer.json
When Kiro looks for an agent:
.kiro/agents/ in the current directory~/.kiro/agents/ in the HOME directoryIf both locations have agents with the same name, the local agent takes precedence with a warning message.
Click the agent name (e.g., "Default") in the bottom bar of the chat input to open the agent picker, then select your custom agent from the list. The switch applies to the current session, and your agent's tools, permissions, and prompt take effect from the next message.
You can also choose a custom agent from the workflow options when starting a new session.
Creating custom agents