Custom Agents

An agent is the configuration that decides how Kiro behaves: which model it uses, which tools it can reach, what it’s allowed to do without asking, what context it starts with, and how it responds. Kiro ships with built-in agents, but the moment you want to tailor any of that to your project, you create your own.

Custom agents are the foundation for much of the rest of this workshop. Scoped tool permissions, bundled context, and MCP servers are all configured on an agent.

An agent is a Markdown file

In v3 an agent profile is a Markdown file with YAML frontmatter. The frontmatter holds the configuration; the body of the document is the system prompt. (A JSON file with the same fields is equivalent. Use Markdown when the prompt is long, JSON when generating configs programmatically.)

---
description: A practice agent for the workshop.
model: claude-opus-4-8
tools: [read, write, shell]
permissions:
  - capability: shell
    effect: allow
    match:
      - "dotnet build *"
      - "dotnet test *"
welcomeMessage: "Ready to work on the workshop exercises."
---

You are a concise pair programmer helping with small C# changes.
Prefer the standard library. Write a test alongside any new method.

The name comes from the filename and the system prompt is the document body, so neither needs a frontmatter field. Everything else (model, tools, permissions, context) lives in the frontmatter.

Where agents live

Agents follow the same project-vs-global split as the rest of the .kiro directory: .kiro/agents/ for this project, or ~/.kiro/agents/ for every project on your machine, with the project copy winning a name clash. One agent-specific wrinkle: a project agent loads only once you’ve trusted the workspace, while global agents are always available.

The agent’s name is its path relative to the agents directory, without the extension. Nested directories are supported, so ~/.kiro/agents/team/planner.md is the agent team/planner.

The frontmatter fields

Field	What it controls	Explored in
`description`	One-line summary of the agent	n/a
`model`	Which model the agent runs on	this lesson
`tools`	Tool categories the agent can use (tags)	this lesson
`permissions`	What runs without asking, and what’s denied	this lesson
`resources`	Files/skills always loaded into context (`file://`, `skill://`)	Steering Files
`mcpServers`	External tools via MCP, defined inline	MCP Servers
`welcomeMessage`	Greeting shown when the agent starts	n/a
(document body)	The system prompt	this lesson

Tools are categories, not individual tools

The tools field takes category tags. Each tag groups related capabilities, so you don’t enumerate individual tools, and when new tools ship under a category, your agent picks them up automatically.

Tag	What it includes
`read`	File reading, directory listing, searching
`write`	File writing, editing, deleting
`shell`	Command execution and process management
`web`	Web fetching
`subagent`	Subagent delegation
`knowledge`	Knowledge base tools
`todo_list`	Task tracking
`@mcp`	All MCP tools from your MCP config
`@builtin`	All built-in tools
`*`	Everything

Tools vs. permissions

These are two different questions, and separating them is the whole point of the model:

tools decides what the agent can see, meaning its capabilities. If a category isn’t listed, the agent can’t use those tools at all.
permissions decides what happens when it uses one: allowed silently, denied outright, or paused to ask you.

A permission rule has four parts: a capability, an effect (allow, ask, or deny), and optional match / exclude glob patterns.

permissions:
  - capability: shell
    effect: allow
    match:
      - "dotnet build *"
      - "dotnet test *"
  - capability: filesystem
    effect: deny
    match:
      - ".env"
      - "secrets/**"

Two rules to remember:

When no rule matches, the default is ask. So the agent above runs dotnet build/dotnet test without prompting, refuses anything touching .env or secrets/, and asks before any other shell command or file operation.
Effects resolve by restrictiveness: deny > ask > allow. A more permissive rule can never override a more restrictive one, so a deny always wins.

Create your first agent

Create the agent file shown above at .kiro/agents/workshop.md. Your project now contains:
- Directory.kiro/
  - Directoryagents/
    workshop.md
Start Kiro and select your agent when prompted:
Terminal window
```
kiro-cli
```
The agent’s name is workshop, the filename without its extension.

With an agent in place, you can scope exactly what it reaches. Next we hand it fresh external tools and knowledge through MCP servers.