Custom agents allow you to tailor Kiro CLI behavior for specific tasks by defining which tools are available, what permissions are granted, and what context is automatically included.
You can create an agent using the /agent create slash command from within a Kiro CLI chat session. By default, it uses AI-assisted mode to generate a full agent configuration based on your description:
> /agent create ✔ Enter agent name: · backend-specialist ✔ Enter agent description: · You are a specialist in backend coding practices ✔ Agent scope · Local (current workspace) Select MCP servers (use Space to toggle, Enter to confirm): markdown-downloader (node), code-analysis (uv) ✓ Agent 'backend-specialist' has been created and saved successfully!
You can also provide a name and options inline:
> /agent create backend-specialist -D "Backend coding specialist" -m code-analysis
Alternatively, use the CLI command directly from your terminal:
kiro-cli agent create backend-specialist
The /agent create slash command and the kiro-cli agent create CLI command share some flags, while others are exclusive to the slash command:
| Flag | Description | Availability |
|---|---|---|
--directory | Where to save the agent (see directory values) | Both |
--from | Template agent to base the new agent on (implies --manual) | Both |
--description | Description of the agent | Slash command |
--mcp-server | MCP server to include (repeatable) | Slash command |
--manual | Use editor-based creation instead of AI generation | Slash command |
The --directory flag accepts two special values in addition to custom paths:
| Value | Description |
|---|---|
workspace | Creates the agent in .kiro/agents/ in your current working directory |
global | Creates the agent in ~/.kiro/agents/ (the default) |
./path or /path | Creates the agent in the specified custom path |
When no --directory is specified, agents are saved to the global directory (~/.kiro/agents/).
If you prefer to define the agent configuration yourself in an editor rather than using AI generation, pass the --manual flag:
> /agent create my-agent --manual
This opens your default editor with a basic agent configuration file. You can also base a new agent on an existing one using --from:
> /agent create my-agent --from backend-specialist
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" }
Start a new chat session - which uses the default agent ("kiro_default") and swap to an agent using the agent slash command
> /agent swap Choose one of the following agents ❯ rust-developer-agent kiro_default backend-specialist
After selecting an agent, you will see the following:
✔ Choose one of the following agents · backend-specialist [backend-specialist] >
Alternatively, start a chat session with your custom agent:
kiro-cli --agent my-agent
Creating custom agents