What Are Custom Agents?

Custom agents are configuration files that tailor Kiro CLI's behavior for specific workflows. By defining available tools, permissions, and automatic context, you create task-specialized AI assistants.

Why Custom Agents?

The default Kiro CLI is general-purpose and asks for confirmation on every tool use. In real development, this creates friction:

• Frequent prompts: Confirmation required for every file read/write
• Missing context: Project-specific rules need to be explained every time
• Tool overload: Unused tools remain available
• Team inconsistency: Different settings per team member

Custom agents solve all of these.

Benefit	Description
Workflow optimization	Task-specific agents boost efficiency
Reduced interruptions	Skip confirmations for trusted tools
Enhanced context	Auto-load project information
Team standardization	Shared configs for consistent environments
Security control	Grant access only to needed tools

Creating Agents

AI-Assisted Mode (Default)

The easiest approach — run /agent create in a chat session:

> /agent create

You'll be prompted for:

1. Agent name
2. Description
3. Scope (local or global)
4. MCP servers to include

Inline creation is also possible:

> /agent create backend-specialist -D "Backend API development specialist" -m code-analysis

CLI Command

kiro-cli agent create backend-specialist

Manual Mode

To edit the JSON configuration directly:

> /agent create my-agent --manual

Opens your default editor with a basic configuration template.

Template-Based

Create a new agent based on an existing one:

> /agent create my-agent --from backend-specialist

Creation Options

Flag	Description	Available In
--directory	Save location (workspace/global/path)	CLI & slash
--from	Template agent	CLI & slash
--description	Agent description	Slash only
--mcp-server	MCP servers (repeatable)	Slash only
--manual	Editor-based creation	Slash only

Configuration File Structure

Custom agents are defined as JSON files. The filename (without .json) becomes the agent name.

{
  "name": "frontend-dev",
  "description": "Frontend development specialist for React projects",
  "prompt": "You are a frontend development expert specializing in React, TypeScript, and modern web development.",
  "tools": ["read", "write", "shell", "code"],
  "allowedTools": ["read", "code"],
  "model": "claude-sonnet-4",
  "welcomeMessage": "Frontend Dev agent ready. What would you like to work on?"
}

Key Fields

name

The agent's identifier, used in displays and command references.

description

Explains what the agent does. Helps users distinguish between multiple agents.

prompt

High-level instructions for the AI, similar to a system prompt. Supports inline text or file references:

{
  "prompt": "file://./my-agent-prompt.md"
}

Relative paths resolve from the agent config file's directory.

tools

List of tools the agent can use:

Specification	Example	Description
Built-in tool	"read", "write", "shell"	Standard tools
MCP tools (all)	"@server_name"	All tools from a server
MCP tool (specific)	"@server/tool_name"	A specific tool
All tools	"*"	Everything available
All built-in	"@builtin"	All built-in tools

allowedTools

Tools permitted to run without confirmation. Supports wildcard patterns:

{
  "allowedTools": [
    "read",
    "code",
    "@git/git_status",
    "@git/git_log",
    "@server/read_*"
  ]
}

Pattern	Matches
"read"	read tool only
"@git"	All git server tools
"@git/git_status"	git_status only
"@server/read_*"	Tools starting with read_
"code_?"	code_ + one character

model

Specifies the AI model. Falls back to default if omitted.

{
  "model": "claude-sonnet-4"
}

welcomeMessage

Displayed when switching to this agent.

keyboardShortcut

Quick-access shortcut. Format: [modifier+]key (modifier: ctrl/shift, key: a-z/0-9).

{
  "keyboardShortcut": "ctrl+1"
}

File Locations

flowchart TB
    subgraph Global["Global Agents<br/>~/.kiro/agents/"]
        G1["aws-specialist.json"]
        G2["code-reviewer.json"]
    end
    subgraph Local["Local Agents<br/>.kiro/agents/"]
        L1["project-dev.json"]
        L2["api-specialist.json"]
    end
    Priority["When same name exists<br/>Local takes precedence"]
    Local --> Priority
    Global --> Priority
    style Global fill:#8b5cf6,color:#fff
    style Local fill:#3b82f6,color:#fff
    style Priority fill:#f59e0b,color:#fff

• Local: .kiro/agents/ (project-specific)
• Global: ~/.kiro/agents/ (shared across projects)

When both contain an agent with the same name, local takes precedence.

Using and Managing Agents

Launch with a Specific Agent

kiro-cli --agent frontend-dev

Switch During a Session

> /agent swap

List Agents

> /agent list

kiro-cli agent list

Set Default Agent

kiro-cli agent set-default frontend-dev

Edit an Agent

> /agent edit frontend-dev

Validate Configuration

> /agent validate

Building Your First Agent

Let's create a simple development agent.

1. Create the Agent

> /agent create dev-helper --manual

2. Edit the Configuration

{
  "name": "dev-helper",
  "description": "General development helper with safe defaults",
  "prompt": "You are a helpful development assistant. Follow project conventions and write clean, tested code.",
  "tools": ["read", "write", "shell", "code"],
  "allowedTools": ["read", "code"],
  "model": "auto",
  "welcomeMessage": "Dev helper ready! What are we building today?"
}

3. Launch with the Agent

kiro-cli --agent dev-helper

4. Test It

> Explain the structure of this project

read and code run without confirmation (they're in allowedTools). write and shell will ask for permission.

Summary

Topic	Details
Custom agents	Config files defining tools, permissions, and context
Creation	/agent create (AI-assisted) / --manual (manual)
Config format	JSON, filename = agent name
Key fields	tools, allowedTools, prompt, model
Storage	.kiro/agents/ (local) / ~/.kiro/agents/ (global)
Switching	--agent name / /agent swap

In Day 5, you'll learn practical agent configurations and advanced options.