Custom Agents

A custom agent is a scoped version of Kiro that you define: its own instructions, its own allowed tools, its own resources, and optionally its own model. Instead of one generalist doing every job at full privilege, you build a small cast of specialists and pick the one whose job matches the task.

What is a custom agent?

Think job descriptions. A “reviewer” that reads code and complains but cannot change anything. A “docs writer” with access to your Markdown and nothing else. A “migration helper” that can run shell commands in one directory. Each is a file in your repository, so the cast travels with the project.

The gain is not only tidiness. An agent whose tool list contains only read cannot delete your working tree, no matter how badly a prompt goes. That is a guarantee about behavior, not a hope about it, and it changes how much freedom you can comfortably grant.

Why it exists

Two problems push in the same direction.

The first is permission fatigue. A general-purpose agent asks about every command it wants to run, and after the twentieth prompt you start approving without reading, which is worse than not asking. A scoped agent with pre-approved safe tools does not interrupt, because it cannot do the dangerous things at all.

The second is prompt sprawl. If you find yourself pasting the same four paragraphs of instructions into every code review session, those paragraphs want to be an agent definition. Same for the model choice: switching to a cheap model for mechanical work several times a day is a pattern begging to be encoded.

How it works

Two formats, one idea. The CLI defines agents as JSON, with fields name, description, tools, allowedTools, resources, prompt, and model. The IDE, since its 1.0 release in June 2026, uses Markdown: YAML front matter for description, model, tools, mcpServers, and permissions, with the system prompt as the document body. Both formats read from the same folders.

A read-only reviewer as CLI JSON:

{
  "name": "reviewer",
  "description": "Reviews code critically; cannot modify anything",
  "tools": ["read"],
  "allowedTools": ["read"],
  "resources": ["file://README.md"],
  "prompt": "You are a strict senior reviewer. Find problems; do not fix them."
}

The same reviewer as an IDE Markdown agent:

---
description: Reviews code critically; cannot modify anything
tools: [read]
---
You are a strict senior reviewer. Find problems; do not fix them.

The tools field takes categories, not tool names. Kiro’s tools documentation lists them as read, write, shell, and web, plus @builtin for the whole built-in set. Naming a category is how you draw the hard line: an agent granted read alone has the file-reading side of Kiro’s built-in toolset and nothing that edits, runs, or fetches.

Scopes. Project agents live in .kiro/agents/ and global agents in ~/.kiro/agents/. Unlike steering, hooks, and skills, which merge, agents supersede: a project agent with the same name as a global one wins, and Kiro warns you about the collision rather than silently picking. Custom agents can also declare their own mcpServers, which is the agent level in MCP’s agent-then-project-then-global precedence.

Using them. In the CLI, /agent create reviewer -D "strict code reviewer" scaffolds one, /agent swap switches mid-session, and kiro-cli --agent reviewer starts directly in one. /upgrade-agent (CLI v2.14.0) migrates V2 configurations to the universal format. In the IDE, an agent appears in the selector the moment you save its file.

Common mistakes

Giving every agent every tool “to be safe.” That recreates the generalist you were scoping away and throws out the one property that made the agent worth defining. The fix: start from the smallest tool set that could do the job and add only what the agent visibly lacks.

A description too vague to route on. “Helps with code” tells neither you nor Kiro when to reach for it. The fix: write the description as the sentence you would say when handing over the task.

Forgetting the model field. Pinning models by job is the underused half of the feature. The fix: a quick-fixer on a cheap model, a reviewer on an expensive one. See Choosing a Model for the multipliers.

Duplicating a global agent name in a project. It works, but the warning is telling you that somebody, eventually, will be confused about which definition ran. The fix: name project agents for the project.

Permissions and safety

Tool categories and permissions are two layers, not one. The tools field decides what the agent has at all. The permission rules decide what it may do with them, capability by capability (fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, power, context, diagnostics, sandbox_network), with deny beating ask beating allow and agent as one of the six scopes alongside Kiro’s own defaults, administration, user, workspace, and session.

Where it fits

Custom agents package who the agent is; skills package what it knows how to do. The two compose: a reviewer agent can load a code-review skill when the request matches. MCP servers can be scoped per agent, and powers add technology-specific bundles. Steering still applies underneath, since it is project context rather than agent identity.

By surface: the CLI and the IDE both define and run custom agents from the same folders in different formats. kiro-cli acp --agent my-agent exposes a specific agent to editors that speak the Agent Client Protocol. Kiro Crew lists agents and agent templates among its capabilities, and agents configured in Kiro Web sync down to local sessions as read-only previews.

Learn more

• Create a custom agent is the guided walkthrough.
• A read-only reviewer agent is the safest first one to build.
• Change the default model covers pinning models per agent.
• Kiro CLI Guide has the full /agent command family.
• Advanced Tutorial puts agents to work on a real change.