Create a Custom Agent

A custom agent is a named persona with its own system prompt, model, and tool set. You create one as a file in .kiro/agents/, and it appears in the agent selector as soon as you save.

When to use this

Create an agent when a job repeats and needs different permissions from your normal work: a reviewer that reads but never writes, a migration agent that must not touch production, a documentation agent with no shell access. One generalist agent accumulates generalist permissions, which is the thing you are trying to avoid.

Steps

1. Choose the scope. Team agents go in .kiro/agents/ inside the repository. Personal agents go in ~/.kiro/agents/. Both folders are shared by the IDE and the CLI.

2. Create the Markdown file. The IDE reads YAML front matter and treats the body as the system prompt.

   .kiro/agents/docs-writer.md

   ---
   description: Writes and edits project documentation only.
   tools: [read, write]
   ---
   
   You maintain the documentation in docs/. Read the source before
   you write. Match the existing headings and tone. Never edit code
   outside docs/, and never run shell commands.

3. Set tools to the smallest set that works. The categories are read, write, shell, web, and @builtin. Leave out anything the job does not need.

4. Add model if the job wants a specific model rather than your default, mcpServers if it needs particular external tools, and permissions for finer rules.

5. Write the body as instructions to the agent, not as a description of it. Say what to do, what to check, and what never to do.

6. Save the file. The agent appears in the IDE selector immediately, and you can switch to it mid-session.

7. In the CLI, create one with /agent create docs-writer -D "writes documentation", and add --manual to edit the configuration directly. Switch mid-session with /agent swap, or start a session as the agent with kiro-cli --agent docs-writer.

Check it worked

Start a session as the agent and ask it to do something outside its remit. A docs-writer with tools: [read, write] should refuse to run a shell command rather than ask permission for one. Then give it a task inside its remit and confirm it works without a stream of approval prompts. Fewer prompts and a hard ceiling are the two payoffs.

Common problems

• The agent does not appear. Check the file is in .kiro/agents/ or ~/.kiro/agents/ and that the YAML front matter parses. Save the file to trigger a reload.
• A name clash. A project agent supersedes a global agent with the same name, and Kiro warns you. Rename one.
• The agent still asks for everything. tools limits categories; individual actions are still permission-checked. Pair the agent with rules in permissions.yaml.
• The prompt reads like a bio. “You are a helpful documentation expert” changes nothing. Concrete rules do.
• Changes need a restart. The CLI hot-reloads agent and MCP settings on save since v2.10.0, so you should keep your history. If a change does not take, check you edited the scope you are running from.

Related

• Custom agents covers the concept and both file formats.
• Build a read-only reviewer agent is the highest-value first agent.
• Kiro CLI Guide lists the agent commands.