Build a Read-Only Reviewer Agent

A reviewer agent reads your code, judges it against your standards, and reports findings. It cannot write files or run commands, which is what makes it safe to let loose.

When to use this

Use it before a pull request, after a long agent session, or as a second pass on anything a generalist agent produced. The read-only ceiling matters most when you want to run the review unattended. A reviewer that could edit would quietly fix what it should have reported.

Steps

1. Write the standards first. A review with no reference document is an opinion. Put your rules in docs/standards.md or in a steering file.

2. Create the agent file in .kiro/agents/ so the whole team gets it.

   .kiro/agents/reviewer.md

   ---
   description: Strict reviewer. Reads everything, changes nothing.
   tools: [read]
   ---
   
   You are the team's strictest reviewer. Check the code under review
   against docs/standards.md. Hunt for correctness bugs, missing error
   paths, and untested edge cases. Report every finding with the file,
   the line, and why it matters. Never propose a patch. Never edit a
   file. If you are unsure, say so instead of guessing.

3. Restrict the tools to read only. Leaving out write and shell removes the categories entirely rather than merely discouraging their use.

4. Add deny rules so the ceiling holds even if the agent configuration changes. Set the fs_write and shell capabilities to deny, either in the agent’s own permissions front matter or in your permission rules. Deny beats ask and allow at every scope, so nothing can grant those capabilities back. Set up permissions.yaml covers the file and the capability list.

5. Scope each run. Ask the agent to review a specific diff, a specific folder, or a specific spec task. A whole-repository review costs context and produces vague output.

6. Start it as its own session: kiro-cli --agent reviewer, or pick it in the IDE agent selector. Switch back with /agent swap when the review is done.

7. Feed findings into work you actually do. A review that nobody acts on is a credit bill.

Check it worked

Ask the reviewer to fix something. It should decline or report that it cannot, rather than opening a diff. Then ask it to review a file with a known problem, such as a missing error branch, and confirm the finding names the file and the reason. A reviewer that only produces praise is not configured; it is guessing.

Common problems

• The agent proposes patches anyway. The tools ceiling stops it writing, not talking. Add “never propose a patch” to the prompt if you want findings only.
• Reviews are generic. The agent has no standards to check against. Point the prompt at a real document.
• The run is expensive. Scope it. Review the diff, not the repository.
• A deny rule blocks too much. Deny always wins, so a broad deny at user scope blocks the agent everywhere. Attach the rule to the agent scope instead.
• The reviewer misses whole classes of bug. Give it a checklist in the prompt. “Check every error path has a test” finds more than “review this code”.

Related

• Create a custom agent covers the file format.
• Set up permissions.yaml explains capabilities and scopes.
• Advanced Tutorial uses this agent as a role in a team workflow.