level-8-the-summoners-circle

Objective

Create an agent at .claude/agents/hero-agent.md with agent frontmatter and a system prompt body.

Why This Matters

Skills are knowledge. Agents are beings. An agent is an autonomous subprocess with its own system prompt, its own tool access, and its own purpose. When Claude encounters a task that matches an agent's description, it can delegate to that agent entirely -- spawning a focused subprocess that works independently and returns with results.

Agents are how Claude Code scales. Instead of one conversation doing everything, you dispatch specialists. A code reviewer that only looks at diffs. A test writer that only touches test files. A documentation agent that reads code and produces docs. Each one scoped, focused, and safe.

The Quest

A circular chamber. Runes etched into the floor in concentric rings. At the center, an empty space. This is a summoning circle. Whatever you inscribe here will have a life of its own. Every summoned being needs a true name. Yours is hero-agent.

You've built spells, voices, tripwires, and knowledge tomes. Now summon a companion -- an autonomous being that can act on its own.

Agents live as .md files. They can go in a project's .claude/agents/ directory, in ~/.claude/agents/ for global access, or in a plugin's agents/ directory. Each one follows the pattern you've seen before: YAML frontmatter on top, content below. But the frontmatter carries more weight here.

Your task:

• Create .claude/agents/hero-agent.md
• Add YAML frontmatter with name, description, color, model, and tools
• In the description, include at least one <example> block showing a user prompt that should trigger this agent
• Pick a color for your agent's badge: blue, cyan, green, yellow, magenta, or red. This is the color that appears in the UI when your agent is active
• Set model to haiku -- agents don't always need the biggest model. Haiku is fast and cheap, good for focused tasks. Other options: sonnet, opus, or inherit (match the parent session)
• Set tools to limit what the agent can do. A read-only agent uses Read, Glob, and Grep. An agent that can't write files or run commands is an agent you can trust to only observe. This is the principle of least privilege applied to agents
• Write a system prompt in the body -- this is the agent's personality, purpose, and instructions
• Choose a specialization: code review, test generation, documentation, refactoring, or something you'll actually use

The description with <example> blocks is how Claude decides when to dispatch your agent. Without examples, Claude has to guess. With them, it knows.

Try it

First, run /reload-plugins so Claude picks up the new agent file. Then type @hero-agent followed by a task in its domain. The @agent-name syntax dispatches the agent as a subprocess -- it works with its own system prompt, completes the task, and returns the result to you.

You can also launch it as a standalone session: claude --agent hero-agent. That starts a fresh Claude session with your agent's system prompt loaded.

To test auto-dispatch: ask Claude something that matches one of your <example> prompts without using @. If Claude spawns the agent on its own, your description and examples are working.

Hints

Hint 1

An agent is a .md file in an agents/ directory. Create yours at .claude/agents/hero-agent.md. The filename (minus .md) becomes how you reference the agent -- so this becomes hero-agent.

.claude/agents/
  hero-agent.md

Hint 2

The frontmatter needs name, description, color, model, and tools:

---
name: hero-agent
description: |
  What your agent does, in one or two lines.

  <example>
  a user prompt that should trigger this agent
  </example>
color: green
model: haiku
tools: Read, Glob, Grep
---

Your system prompt here -- the agent's personality, purpose, and instructions.

Verification

When you're ready, run /claude-code-hero:verify to check your work.

Filesystem Check

• Path: .claude/agents/hero-agent.md
• Command: test -f .claude/agents/hero-agent.md && echo "exists" || echo "missing"

Content Check

• The file has valid YAML frontmatter (content between --- delimiters at the top)
• Frontmatter contains name, description, color, model, and tools fields
• The description includes at least one <example> block

Further Reading

• Subagents -- official docs on creating agents, frontmatter fields, tool restrictions, and permission modes

Connection

The circle glows. Something stirs inside it -- your creation. It has a name, a purpose, and the autonomy to act on both.

The guide leading you through these quests? That's an agent. dungeon-master.md. You've been talking to one this entire time. Same frontmatter. Same markdown body. Same pattern.

Now count the artifacts on your belt. A command (hero-spell). A rule (hero-protocol). A hook that connects them. A skill (hero-knowledge). And now an agent (hero-agent). Five components. Each one a different kind of power.

What if you could bind them all together into a single artifact? A package that anyone could install and use?

One final quest remains.