AWS Kiro Custom Agents: Your First Agent in 15 Minutes

A hands-on tutorial for building a custom agents

Kiro CLI ships with a default agent (kiro_default), but custom agents let you go further. A custom agent is a named configuration that gives an LLM a specific role, a defined set of tools, and context loaded automatically at startup. Rather than repeating the same prompt setup every session, a custom agent captures it once and makes it instantly available to you and your team.

This tutorial will walk through building a code-reviewer agent to review code with controlled tool access and automatically load a project README on startup. By the end, you will have a working local agent file you can activate, swap to, and commit to version control.

What you will build: a code-reviewer agent that reads files and runs shell commands without prompting, loads your project README automatically, and greets you when activated.

Time: ~15 minutes

Prerequisites

• Kiro CLI installed and authenticated (version >= 2.1)

• An active chat session (kiro-cli chat)

• A project directory with a README.md under version control (git)

---

Step 1 — Understand where agents live

Kiro looks for agents in two places:

Location

• .kiro/agents/ in your project — Scope: only available for the project

• ~/.kiro/agents/ — Scope: available everywhere

When both locations contain an agent with the same name, the local version takes precedence. This makes local agents a good choice when you want behavior tailored to a specific project, while global agents are better suited for general-purpose assistants you reach for everywhere.

For this tutorial, a local agent keeps things contained to your project.

To begin, create the agents directory in the project:

mkdir -p .kiro/agents

With the directory in place, the next step is creating the configuration file.

---

Step 2 — Create the agent file

Create .kiro/agents/code-reviewer.json with the following content:

{
  "name": "code-reviewer",
  "description": "Reviews code changes. Reads files and runs git commands without prompting.",
  "prompt": "You are a thorough code reviewer. Focus on correctness, clarity, and security. Be concise.",
  "tools": ["read", "shell"],
  "allowedTools": ["read", "shell"],
  "resources": [
    "file://README.md"
  ],
  "welcomeMessage": "Ready to review. Share a file path or paste a diff."
}

What each field does:

• tools — declares what the agent can use

• allowedTools — declares what runs without a permission prompt

• resources — files loaded into context when the agent starts

• welcomeMessage — shown when you switch to this agent

Save the file. Kiro detects new agent files automatically, no restart is required for the agent to appear in the list

Note on config changes: adding a new agent file takes effect immediately. Changes to an existing agent’s configuration, however, take effect the next time you activate the agent (via /agent swap). A running session does not reload mid-conversation.

---

Step 3 — Activate the agent

Start a chat session:

kiro-cli chat

Inside the session, swap to your new agent:

 /agent

Select code-reviewer from the list. You will see:

✔ Choose one of the following agents · code-reviewer
Ready to review. Share a file path or paste a diff.
code-reviewer · auto

Your README.md is already loaded in context. To confirm, ask the agent something about it:

code-reviewer · auto
What does this project do?

The agent answers using the README content. No file-reading prompt appears because read is in allowedTools and runs silently by design.

---

Step 4 — Test tool permissions

To see the permission boundary in action, ask the agent to inspect recent changes:

code-reviewer · auto 
What files have changed?

The agent runs git status without prompting, because shell is pre-approved within allowedTools. Now try something outside its approved list:

code-reviewer · auto 
Write a summary to NOTES.md

Kiro will prompt you for permission before writing, because write is not listed in allowedTools. This is the security boundary working as intended.

---

Step 5 — Restrict write access with toolsSettings

You decide the agent should be able to write, but only to a reviews/ directory. Exit Kiro and update the config to add write capability to both tools and allowedTools:

{
  "name": "code-reviewer",
  "description": "Reviews code changes. Reads files and runs git commands without prompting.",
  "prompt": "You are a thorough code reviewer. Focus on correctness, clarity, and security. Be concise.",
  "tools": ["read", "write", "shell"],
  "allowedTools": ["read", "shell", "write"],
  "toolsSettings": {
    "write": {
      "allowedPaths": ["reviews/**"]
    }
  },
  "resources": [
    "file://README.md"
  ],
  "welcomeMessage": "Ready to review. Share a file path or paste a diff."
}

Create the directory:

mkdir reviews

Start a new session with kiro-cli chat (config changes take effect on next chat activation), and swap to the code-review agent with commands from Step 3:

# activate new session
kiro-cli chat
# activate the code-review agent
/agent

Now ask the agent to write a review:

code-reviewer · auto 
Review project files and save findings to reviews/main-review.md

The agent writes to reviews/main-review.md without prompting. An attempt to write anywhere else will still require confirmation.

---

Troubleshooting

Agent does not appear in the /agent list

Check that the file is valid JSON — a missing comma or bracket will silently prevent the agent from loading. A JSON linter or jq . .kiro/agents/code-reviewer.json can surface syntax errors quickly.

Resource file not found warning

Kiro resolves file:// paths relative to the project root. If README is in a subdirectory, update the path to match: file://docs/REAME.md

Config changes not taking effect

Changes to an existing agent require re-activation. Run /agent to change agents and then swap back to reload the config in the current session.

---

Conclusion

• Agent files live in .kiro/agents/ (local) or ~/.kiro/agents/ (global)

• tools declares availability; allowedTools removes the permission prompt

• toolsSettings constrains what allowed tools can touch (e.g., allowedPaths for write operations)

• resources pre-load files into context at startup

Next steps

• Move the prompt to a separate file: "prompt": "file://./prompts/code-reviewer.md" for easier editing

• Commit .kiro/agents/code-reviewer.json to version control so teammates get the same agent automatically

• Read the official configuration reference for all available fields

Buy me Coffee