🛠️ Creating it in practice

The YAML block delimited by --- at the top of the file. It's the config area: Claude reads it before processing the content.

Without understanding the frontmatter, every field seems like magic. Understanding the structure separates what configures from what instructs.

Frontmatter = config; body = instructions. They're distinct areas with distinct purposes.

The agent’s unique identifier. Appears in the /agents, in the FleetView log and lets you invoke it by name ("use the security-reviewer").

A bad name prevents direct invocation and clutters the catalog. Descriptive kebab-case is the convention.

Kebab-case; no spaces; name = direct invocation handle.

YAML list of tools the agent can call: Bash, Read, Write, WebFetch, etc. Omitting it grants full access—which is rarely ideal.

Limiting tools is the first layer of security. An agent that can only read can’t delete anything.

Least privilege principle; explicit list > omitted full access.

Selects which Claude model runs the agent: sonnet (default), haiku (fast/cheap), opus (deep). Omit to inherit the parent process’s model.

It’s the cost lever. Mechanical tasks in Haiku; deep analysis in Opus. Choosing deliberately saves credits.

Inherits if omitted; sonnet = safe default; haiku = task batches.

color sets the color in FleetView; memory enables persistent notes; isolation: worktree runs in an isolated git branch.

Optional fields unlock advanced use cases without cluttering the basic config. You choose when to grow.

Optional = progressive; add it when the situation calls for it.

Without name the file is ignored. Without tools gets full access. Without model inherits from the parent. Without description is never selected automatically.

Invisible defaults cause silent bugs. Knowing what each omission activates prevents surprises in production.

name is required; description = automatic routing; tools = security.

When you ask for something, Claude reads only the name + description of all available agents and decides which one to use without seeing the body.

It’s the central routing mechanism. Understanding how Claude decides which agent to call changes how you write the description.

Routing by description; the body is only included when the agent is activated.

A good description includes: (1) what the agent does, (2) when to use it, and (3) activation examples — like an expert dictionary entry.

It’s the most-read text in your agent—it’s read every time Claude makes a decision. One bad sentence = the agent is never called or is always called incorrectly.

What it does + when to use it + activation examples.

Three classic mistakes: (1) too vague—the Claude never chooses; (2) too long—wastes catalog tokens; (3) identical to general-purpose—the agent never beats the default selection.

Recognizing the error avoids review. A poor description is invisible until you realize the agent never triggers.

Specific > generic; concise > long; differentiated > a copy of the default.

Add explicit "TRIGGER (when to invoke)" and "SKIP (when not to invoke)" sections to the description — the pattern used in production agents.

Eliminates false positives. Claude takes "don’t trigger for X" literally and follows it — reducing unnecessary invocations.

TRIGGER = green light; SKIP = explicit red light in the description.

The method: invoke the agent with real scenarios, observe when it doesn’t trigger or triggers incorrectly, refine the description, and retest — a short cycle.

No one gets it right on the first try. The fast edit-test cycle is the skill that separates functional agents from those that are perpetually "almost ready."

Edit → test → adjust cycle; feedback is the signal, not intuition.

Reading and analyzing real agent descriptions from the Claude Code ecosystem (claude-code-guide, general-purpose, Explore)—what worked and why.

Real examples teach more than theory. Seeing a production pattern calibrates your expectations.

Pattern matching; read existing agents as an exercise.

The first line of the body defines the agent’s role: "You are an expert in X who does Y." This sentence anchors all the behavior that follows.

Agents without a declared role drift and become generic. The role is the compass that guides every decision within the task.

Role = identity; the more specific it is, the more consistent the output.

Numbered list defining the protocol: 1. Read X 2. Identify Y 3. Produce Z. The agent follows the list as an internal checklist.

Without steps, the agent interprets creatively—sometimes well, sometimes not. Numbered steps make behavior reproducible.

Reproducibility; each step = a verifiable action.

A body section that specifies exactly what format the report should use: bullet list, table, JSON, prose — with a minimal example if helpful.

The orchestrator processes the agent’s output. An unexpected format breaks the chain. Specifying the output is part of the agent’s contract.

Format = contract; the orchestrator consumes the output.

"DO NOT" section with explicit prohibitions: don't delete files, don't make commits, don't ask the user, don't make up data.

Negative instructions are stronger than positive ones for guardrails. The agent remembers "never X" better than "sometimes don't X".

A negative guardrail is stronger; a list of prohibitions prevents accidents.

You can embed permanent context in the body: fixed folder paths, project conventions, lists of available MCP tools.

Context in the body avoids repeating it in the invocation prompt. The agent already knows where things are before receiving the task.

Permanent context vs. invocation context; the body is the preloaded briefing.

Minimum viable body = role + 3–5 steps + output format. A richer body adds examples, context, and edge cases. When each is sufficient.

Perfectionism paralyzes. Knowing when the minimum is enough and when it’s worth investing more is a practical skill.

Agent MVP; iterate after the minimum works.

Bash, Read, Write, Edit, WebFetch, WebSearch, Agent, Grep, LS — each tool has its purpose and what it lets you do in the system.

You can’t grant permission for what you don’t know. Knowing the catalog is a prerequisite for informed configuration.

Catalog: Bash=executes, Read=reads, Write=creates, Edit=modifies, Agent=child subagent.

A read-only agent needs Bash (grep), Read, and Grep — no Write or Edit. Define the scope by the task type, not by “what if it’s needed.”

Agents with excessive access cause accidental damage. Least privilege makes the agent predictable and auditable.

Read-only agents = safer; Bash+Write = only when necessary.

The field disallowed-tools prohibits specific tools even if the parent profile allows them — an additional layer of explicit blocking.

When the agent inherits permissions from a broad profile, the blocklist is the only way to exclude what it shouldn’t use.

Blocklist complements allowlist; explicit overrides inherited.

MCP tools (Model Context Protocol) extend the catalog: access to databases, external APIs, remote file systems — each registered MCP server becomes a tool.

MCP multiplies the agent’s capabilities. Knowing how to grant (or block) access to a specific MCP server is a key skill.

MCP server = set of external tools; name in tools: = registry entry.

How to use the /agents to inspect each agent's tool profile before running it — identify excessive permissions.

Pre-execution auditing is the habit that prevents accidents. "Let it run and see what happens" is a recipe for data loss.

Review before running; /agents as an inspection tool.

Typical profiles: (1) Reader [Read, Bash(grep)] (2) Analyst [Read, WebFetch, Bash] (3) Builder [+Write, Edit] (4) Orchestrator [+Agent]. Each profile has a target use.

Templates speed up creation. Instead of starting from scratch, you choose the closest profile and adjust it.

4 base profiles; fine-tune for each use case.

Project: .claude/agents/ in the repository root. Global: ~/.claude/agents/ in the home directory. One is local to the repo; the other is available in every project on the machine.

Putting it in the wrong place makes the agent disappear (project) or leak into contexts where it shouldn't exist (global).

.claude/agents/ = project; ~/.claude/agents/ = global; scope determines visibility.

Global is ideal for universal-use agents: code reviewers that work across projects, researchers, and personal documentation agents.

Creating everything as global pollutes every project’s catalog. Knowing how to distinguish them reduces confusion during automatic selection.

Global = project-agnostic; project = specialized for the repo’s domain.

A project is ideal for agents that know the repository’s specific domain: folder structure, naming conventions, local scripts.

A project agent can embed the exact repo paths in its body — context a global agent would never have.

Repo-specific context = project agent advantage.

When there are two agents with the same name (one project-level, one global), the project-level one takes precedence—allowing local overrides of global behavior.

The override is a feature, not a bug. You can adapt a global agent for a specific project without changing the global one.

Project overrides global; intentional override is a valid technique.

Project agents live in git alongside the code — diff, blame, rollback. Global agents live outside the repo and need their own strategy (dotfiles, symlinks).

Versioning the agent alongside the code ensures the team uses the same version — with no silent drift between environments.

Agent = code; versioning = traceability; dotfiles for global configuration.

Conventions for keeping the catalog readable: domain prefixes (sec-, doc-, infra-), README.md in the agents folder, explicit deprecation.

With 20+ agents, the catalog becomes a problem without organization. Structuring it from the start saves future refactoring.

Prefixes + README + deprecation = a sustainable catalog.

The command /agents is the management panel: lists all available agents (built-in + custom), opens the creation wizard, and lets you inspect any agent.

It’s the practical entry point for everything Track 2 teaches. Mastering the command means mastering the work interface.

/agents = dashboard; list + inspect + create everything in one place.

When creating via /agents, Claude guides you through a conversation: asks about the purpose, suggests a name/description/tools, and generates the file — you review and adjust it.

Guided creation is faster than writing from scratch. But understanding the result lets you correct what the assistant got wrong.

AI-assisted generation + human review = ideal creation workflow.

Claude semantically matches the request to the available descriptions. Order of preference: (1) direct invocation by name, (2) strong description match, (3) general-purpose as a fallback.

Understanding the algorithm lets you influence selection: write descriptions that beat the general-purpose agent in the cases that matter.

Direct > semantic > fallback; a strong description beats general-purpose.

Techniques for diagnosing incorrect selection: inspect descriptions of competing agents, identify semantic overlap, ask Claude to explain its choice.

"The wrong agent was called" is the most common bug in overgrown catalogs. Diagnosing is faster than guessing.

Semantic overlap = conflict; clear distinction = precise selection.

Complete exercise: create a code review agent (code-reviewer) from scratch — frontmatter, description with TRIGGER/SKIP, body with role+steps+format+what not to do.

It’s the culmination of all of Track 2. After this exercise, you’ll leave with a real agent running in your environment.

From zero to functional; all fields in harmony; final test.

T3 goes deeper into models and cost (haiku vs opus for each type of agent). T4 expands to Codex and multiple environments. Track 2 is the core that both amplify.

Context about what comes next helps you prioritize: if cost matters right now, skip to T3. If the environment is different, T4 is waiting.

T2 = create; T3 = optimize; T4 = expand to other environments.