Claude Code Agents: How to Install and Use Subagents

Claude Code can already read your repository, run commands, and edit files on its own. Subagents push that further: they let you hand a narrowly scoped job to a separate assistant that carries its own instructions, its own tool permissions, and — most importantly — its own context window. This guide covers what subagents are, how the .claude/agents directory is laid out, what belongs in the frontmatter, when delegation actually helps, and how to install ready-made agents from the ToolZip agents catalog with a single command.

What is a Claude Code subagent?

A subagent is a specialized configuration of Claude Code that your main session can delegate work to. Instead of one assistant juggling every task inside a single growing conversation, you define focused helpers — a code reviewer, a test writer, a database tuner — each with a system prompt tuned for one job. When Claude decides a task matches a subagent's stated purpose, it launches that subagent, lets it work in isolation, and returns the result to the main thread.

The defining benefit is context isolation. A subagent runs in a fresh context window, so a long investigation, a noisy test run, or a large file dump stays out of your primary conversation. That keeps the main thread focused and slows down context exhaustion on big tasks. In short, subagents give you:

• Separation of concerns — each agent has one clear responsibility and prompt.
• A clean context window — the subagent's back-and-forth does not pollute the main session.
• Scoped tool access — you can restrict what an agent is allowed to do.
• Reusability — a well-written agent works across every project you drop it into.

How the .claude/agents directory works

Subagents are plain Markdown files. Claude Code loads them from two locations, and the scope determines where a given agent is available:

• Project agents live in .claude/agents/ at the root of your repository. They ship with the project, so anyone who clones it gets the same helpers.
• User agents live in ~/.claude/agents/ in your home directory. They follow you across every project on your machine.

When an agent name exists in both places, the project version wins. That precedence lets a repository override a personal default with a project-specific variant. Each file is named after the agent it defines — for example code-reviewer.md — and Claude discovers it automatically on startup, no registration step required. You can inspect and manage what is loaded with the /agents command inside a session.

Anatomy of an agent file: frontmatter and system prompt

Every agent file has two parts: a YAML frontmatter block that describes the agent, and a Markdown body that becomes the subagent's system prompt. Here is a complete example you might save as .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Expert code review specialist. Use proactively after writing
  or changing code to catch bugs, style issues, and security risks.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked, review the most recent
changes for correctness, readability, and security. Run git diff to see
what changed, then report findings grouped by severity with concrete
fixes. Do not modify files unless explicitly asked.

The frontmatter fields do the configuration work:

The description is the single most important field. It is the routing signal Claude uses to pick an agent, so write it in terms of the trigger, not just the title. Phrases like "use proactively after" or "invoke when" make automatic delegation far more reliable.

When should you reach for a subagent?

Subagents are not free — spinning one up starts a fresh context that cannot see your main conversation's history. Use them when that trade-off pays off:

• Repetitive, well-defined jobs such as reviewing diffs, writing tests, or generating documentation.
• Context-heavy exploration like searching a large codebase, where you want the noise kept out of the main thread.
• Specialized expertise — a security auditor, an accessibility checker, or a language specialist with a domain-tuned prompt.
• Restricted operations where you want an agent that can read and analyze but never edit or run destructive commands.

Skip the subagent for quick, one-off edits or anything that depends heavily on the conversation you are already having. Delegation shines on discrete tasks with a clean handoff, not on tightly coupled back-and-forth.

Installing agents from the ToolZip catalog

You do not have to write every agent yourself. The ToolZip agents hub is a curated, searchable catalog of Claude Code subagents drawn from the open-source claude-code-templates project. Each listing shows the frontmatter, the system prompt, the tools it uses, and a one-line install command. To add an agent, run the command from your project root:

npx claude-code-templates@latest --agent="code-quality/code-reviewer" --yes

The installer drops the agent file into your local .claude/agents/ directory. The value passed to --agent is the catalog path in category/name form, which matches the URL of the component page on ToolZip. The --yes flag skips the confirmation prompt for non-interactive setup. After it finishes, start Claude Code (or run /agents) and the new subagent is available immediately — automatically when its description matches, or on demand when you ask for it by name.

Example agents worth trying

These are good starting points that map to everyday development work. Browse each one's page for the full prompt before installing:

• code-quality/code-reviewer — a review specialist that inspects recent changes for bugs, style, and security.
• development-team/frontend-developer — a UI-focused agent for building and refining components.
• database/database-optimizer — an agent that analyzes slow queries and proposes indexing and schema fixes.
• devops-infrastructure/deployment-engineer — a helper for CI/CD pipelines and release workflows.

Agents pair naturally with the rest of your setup. Once you have a few installed, explore slash commands for repeatable prompts and MCP servers for connecting external tools and data. The full Claude Code section ties all of these component types together.

Writing your own subagent

Rolling your own is quick once you know the shape of the file. A reliable workflow:

1. Create .claude/agents/ in your project (or ~/.claude/agents/ for a personal agent).
2. Add a Markdown file named after the agent, for example test-writer.md.
3. Write frontmatter with a precise name and an action-oriented description that states when to invoke it.
4. Add a tools allowlist if the agent should be constrained; leave it out to inherit everything.
5. Write the system prompt in the body: define the role, the steps to follow, and what the agent must not do.

A useful shortcut is to install a catalog agent close to what you need, then open the generated file and edit the prompt. Starting from a working example is faster than a blank page, and it shows you the conventions that make an agent behave predictably.

Tips for reliable delegation

• Be specific in the description. Vague descriptions lead to the agent being ignored or triggered at the wrong time.
• Grant the minimum tools. A read-only reviewer should not have write or shell access it never needs.
• Keep each agent single-purpose. One clear job beats a sprawling prompt that tries to do everything.
• Invoke explicitly when it matters. Ask Claude to "use the code-reviewer subagent" to force delegation instead of leaving it to automatic routing.
• Version project agents in git. Committing .claude/agents/ gives your whole team the same helpers.

Subagents are one of the highest-leverage ways to make Claude Code do more without cluttering your main session. Start with a proven agent from the catalog, tune the prompt to your codebase, and add specialists as your workflow demands them.