Create a focused Agent with clear boundaries
Define a role, tool scope, and completion criteria, then verify a delegated task.
ExtensionsGive a repeated task a focused role#
An Agent combines a description, model choice, tool access, and instructions. Here you will create docs-reviewer, which reads Markdown and reports issues without editing it.
Choose the project and creation method#
Select your project first. @Agent inserts an Agent-creation tag in the composer; it does not immediately create a definition. The right-side Agents → Create Agent shortcut starts the same conversation flow.
Definitions are stored in .claude/agents/name.md for a project or ~/.claude/agents/name.md for personal use. The full Agent manager also offers Blank, Code Reviewer, Test Runner, and Docs Writer starting templates. The example below uses an explicit configuration so the allowed tools match its task.
Create the reviewer#
- Select @Agent and ask: “Create a project Agent at
.claude/agents/docs-reviewer.mdusing the definition below. Do not replace an existing file without showing me its differences.” - Include this definition:
---
name: docs-reviewer
description: Review specified Markdown files for unclear steps and broken local links.
model: inherit
tools: Read, Grep, Glob
disallowedTools: Write, Edit, Bash
permissionMode: default
maxTurns: 12
---
Read only the files requested by the caller.
Report unclear instructions and local links whose targets cannot be found.
For each finding, include the file, location, and supporting evidence.
List anything you could not inspect. Do not modify files.
- Review the created file. Open it from the right-side Agents list to inspect or edit its configuration and instruction body; click Save after changes.
- Start a new conversation if the definition is not yet listed, then request a review of an existing Markdown file.
Understand the fields#
| Field | Meaning and a useful choice |
|---|---|
| Name | Definition filename; use letters, digits, hyphens, or underscores |
| Description | Explains when to delegate to this role; name the actual task |
| Model | inherit follows the parent; named model aliases depend on the configured provider |
| Tools | Allowed tool names, entered as comma-separated tags; the example needs Read, Grep, Glob |
| Disallowed Tools | Explicit exclusions; this reviewer does not need Write, Edit, or Bash |
| Permission Mode | Uses SDK values such as default or plan, not the chat labels code/ask; keep default for this example |
| Max Turns | Bounds the Agent's iterations; choose enough for the file list |
| Memory | Optional user or project memory scope; leave unset for the first review |
| Skills | Names of existing Skills to preload; leave empty unless the task needs them |
The editor has Edit, Preview, and Split view modes. Preview checks formatting; it does not execute the Agent.
Delegate and verify#
Delegate README.md to docs-reviewer.
Return unclear setup steps and broken relative links, with locations.
Do not fix them yet. Tell me if the Agent cannot inspect a target.
Inspect the delegation record, then spot-check one finding and one valid link. The intended outcome is a file-based report and no edits. A separate Agent context does not create an isolated copy of project files.
Troubleshoot the definition#
- Agent absent: check
.claude/agents/, filename, project scope, and the saved file; retry in a new conversation. - Tool denied: compare the requested operation with Tools and Disallowed Tools. This example intentionally cannot run shell commands.
- Model unavailable: use
inheritor a model actually available to the selected provider. - Task ends early: narrow the file list or raise Max Turns after inspecting unfinished work.
Next steps#
Put reusable review instructions in a Skill, compare extension types, and review permissions before adding write tools.