It's an Agent, Not a Command.
Walks through the two-part structure of a Claude Code agent file and shows why the description field, written as trigger examples, is what determines whether an agent activates at the right moment.
Building a Claude Code plugin feature that needs to keep working through several steps on its own, the reflex is to reach for a command. That reflex is wrong when the task runs autonomously rather than firing once on a typed instruction. What that situation calls for is an agent, and the file that defines one has a specific shape worth getting right.
Two parts: frontmatter and body
An agent is a single markdown file split into two parts. On top sits YAML frontmatter: a name written in lowercase with hyphens, a description that tells Claude when to fire the agent, a model setting usually left as inherit, a color drawn from a small set tied to the kind of work, and an optional list of tools. Leaving the tools field out entirely gives the agent access to every tool that exists, which is a meaningfully different choice than naming a specific subset. Below the frontmatter, the rest of the file is markdown addressed directly to the agent, written as "you are," "you do," and that text becomes its system prompt.
The description field is what makes it fire
This is the anchor of the whole format: the description field decides when the agent actually runs. The pattern is fixed rather than a suggestion. It opens with "Use this agent when," followed by two to four worked examples, and each example has four parts: the setup, the user's request, what the agent would say back, and a short note on why that example fits the trigger. Skip the examples and Claude has nothing concrete to match against when deciding whether to invoke the agent, which means an agent with a vague or example-free description can sit unused even when it is exactly the right tool for a task.
What the format nails down
The file format itself is precise on several points. Names are lowercase with hyphens, examples are required in that fixed four-part shape, and the body follows a five-part structure: responsibilities, process, standards, output, and edge cases. These are not loose conventions; deviating from them tends to produce an agent that Claude either cannot trigger reliably or applies inconsistently.
What the format leaves to you
The format does not make several judgment calls for you. It does not decide which model tier an agent should run on, whether a given task is genuinely agent-shaped or would work better as a plain command, or how one agent should hand work off to another. Those decisions live in the body text a person writes, not in any frontmatter field, which means two agents built to the same spec can still behave very differently depending on the judgment baked into their prompts.
Key takeaways
- An agent file has two parts: YAML frontmatter (name, description, model, color, optional tools) and a body that becomes its system prompt.
- Leaving the tools field out gives the agent every available tool, not a safe default subset.
- The description field must open with "Use this agent when" and include two to four four-part examples, or Claude has nothing to trigger against.
- The body follows a five-part structure: responsibilities, process, standards, output, edge cases.
- Model tier, agent-versus-command scoping, and hand-off logic between agents are judgment calls the format does not make for you.
Who this is for
Anyone building a Claude Code plugin that needs autonomous, multi-step behavior rather than a single-shot command, especially someone whose agent seems to exist but never actually fires, since a missing or thin description is the most common cause.
Chapters
Full transcript(auto-generated, with timestamps)
The naive framing: "I need a command"
[0:00]Extending a plug-in, you reach for command first. A command only runs when typed. What you want here keeps going on its own through several steps. That's an agent, the file that builds it. An agent
The file, in two parts — frontmatter and body
[0:10]Is one markdown file in two parts. On top, YAML front matter, a name in lowercase with hyphens, a description that tells Claude when to fire the agent, a model usually set to inherit, color from a small set tied to the kind of work, and an optional list of tools. Leave tools out and the agent gets every tool there is. Below the front matter, the rest of the file is markdown written straight to the agent, you are, you do. And that text becomes its system prompt.
The anchor: the description field is the trigger
[0:34]The description field decides when the agent runs. Say you want one that reviews Python code for security issues. The pattern is fixed. Use this agent when, followed by two to four examples, each with four parts, the setup, the user's request, what the agent would say back, and a note on why it fits. Skip the examples and Claude has nothing to match the trigger against. The file format itself is precise. Names are lowercase with hyphens. Examples are required in a fixed shape, and the body follows a five-part structure, responsibilities, process, standards, output, edge cases. What the format
Precise here, open there
[1:05]Doesn't decide for you, which model tier to pick, whether a task is really agent-shaped or just a command, and how one agent hands off to another. Those calls happen in the body text you write, not in the front matter. A Claude code agent is one file, a description with examples that decides when it runs, and a body that decides what it does once it's running. Your turn. Open a Claude code session and paste this. Create an agent for my plug-in that reviews Python code for security vulnerabilities. Then check
Carry-out
[1:31]Four things. Does the description start with use this agent when and include at least two examples? Is the model set to inherit rather than a specific model hardcoded in? Does the tools list
Your turn
[1:40]Include only what a reviewer actually needs, reading and searching code, say, instead of leaving tools out entirely? And does the body address the agent directly in second person? Those four checks are your gate. It's an agent, not a command. Lay 'em in for bear.
