Claude Operator: Prompt to Autonomy · 20 min · 140 XP
Defining a subagent: description, tools, model
Write an agent file whose every field is a decision.
A subagent is a markdown file with frontmatter. Project agents live in .claude/agents/; personal ones in ~/.claude/agents/ and are available across all your projects. The frontmatter configures it; the body becomes its system prompt.
--- name: code-reviewer description: Reviews code for quality and best practices tools: Read, Glob, Grep model: sonnet --- You are a code reviewer. When invoked, analyze the code and provide specific, actionable feedback on quality, security, and best practices.
The description is a routing decision, not a label. It's what the main session reads to decide whether to hand work over, so it needs a trigger, a responsibility and an exclusion: when to use this agent, what it's answerable for, and what it should not be used for. "Reviews code" is a label. "Reviews a diff for correctness and security after changes are written; does not write or fix code" routes correctly and, just as importantly, declines correctly.
tools is the strongest line in the file. Omit it and the agent inherits the full tool set; list tools and that's all it has. A researcher with Read, Glob, Grep cannot edit your files — not "has been asked not to", cannot. Write the list even when it feels redundant, because that's the field that makes a read-only agent actually read-only.
model fits the worker to the job: a fast model for mechanical, well-specified work, a stronger one where the reasoning is the deliverable. inherit uses the parent session's model. The tradeoff is real in both directions — running everything on the most capable model is expensive for tasks that are essentially search, and running a subtle architectural review on the cheapest one wastes the whole delegation.
Practice. Find how your installed version manages agents and see what's already defined. Create a read-only researcher that inspects files and returns evidence without editing. Sharpen its description until it contains a trigger, a responsibility and an exclusion. Give it only the tools its job needs, then confirm an unnecessary write is unavailable to it. Choose its model deliberately and write one sentence on the tradeoff.
Loading your workspace…