Claude Code's `/agents` Command: Managing Subagents from the Session

Claude Code ships with a built-in slash command, /agents, that opens an in-session interface for managing subagents – specialized helpers that Claude can spawn to handle a specific kind of work in an isolated context window. This article walks through what /agents actually exposes, where the underlying files live on disk, how invocation works, and the patterns worth using.

Everything below is checked against Anthropic’s official docs:

What /agents opens

Type /agents in a Claude Code session and you get a tabbed interface:

Running tab Lists live subagents currently spawned inside the session. From here you can open one to see its conversation, or stop one that’s spinning on something you no longer care about.

Library tab Lists every subagent definition Claude Code can see – built-in, user-level, project-level, and plugin-provided. From the Library you can:

The Library tab is the main configuration surface. Most of this article is about what lives there and how to populate it.

Subagents vs agents

In Claude Code docs and UI these terms refer to the same thing – a scoped helper invoked from the main session, running in its own context window. “Subagent” is the canonical term; “agent” is shorthand.

There is a separate concept called background agents (managed via the claude agents CLI command, not /agents). Those are full parallel Claude Code sessions running detached, conceptually different from in-session subagents. This article is about the in-session kind that /agents manages.

Where subagents live on disk

Subagents are Markdown files with YAML frontmatter. Claude Code looks for them in five scopes, with this priority order (highest wins):

  1. Managed settings – organization-wide policy, applied by IT
  2. --agents CLI flag – session-scoped, current invocation only
  3. .claude/agents/ in the project root – checked into git, shared with the team
  4. ~/.claude/agents/ in your home dir – yours, applied across all projects
  5. Plugin agents/ directories – shipped by installed plugins

Each scope is scanned recursively. You can organize files into subfolders (agents/review/, agents/research/) without affecting identity – only the name field in frontmatter matters for resolution.

File format

A subagent file looks like this:

---
name: changelog-writer
description: Writes a changelog entry in asset/docs/changelog/ before a git commit. Use proactively whenever the user asks to commit.
model: sonnet
tools:
  - Read
  - Write
  - Bash
  - Grep
---

You are a changelog writer for this project. Your job is to inspect the staged
and unstaged diff, then produce a Markdown changelog file in
`asset/docs/changelog/` with the filename pattern `YYYY-MM-DD-HHMM-slug.md`.

The article must explain:
- Why the change was made (problem, motivation)
- How it works (architecture, key decisions)
- What changed (files added, modified, deleted)
- Technical debt and unexplored issues
- Future considerations

Keep prose tight. No marketing language. Read the existing changelogs in
`asset/docs/changelog/` to match the house style.

The frontmatter fields:

Field Purpose
name Unique identifier. How the subagent is invoked (@changelog-writer).
description Plain-language summary used by automatic delegation. Be specific about when this subagent should be picked.
model inherit (default), an alias (sonnet, opus, haiku), or a full ID (claude-opus-4-7).
tools Allowlist. Only listed tools are available to the subagent.
disallowedTools Denylist. Useful when you want everything except a few destructive ones.

The Markdown body is the system prompt for the subagent.

Invocation

Two paths get a subagent running:

Automatic delegation. Claude reads the description field of every available subagent at session start. When you give the main session a task that semantically matches one of those descriptions, Claude can spawn the matching subagent on its own. This is why the description matters – “writes a changelog before commit” is delegation-friendly; “useful helper” is not.

Explicit mention. Type @subagent-name in a prompt and Claude invokes that subagent directly. Example: “Have @changelog-writer draft the entry for these changes.”

You can mix the two. A single turn can call out one subagent by name and let Claude delegate to another implicitly.

Bundled subagents

Claude Code ships with a small set:

These show up in the Library tab alongside any custom ones you’ve added. You can read their definitions to see how Anthropic structures system prompts and tool scoping – a useful reference when writing your own.

Model selection per subagent

The model field gives you three shapes:

Practical rule: cheap, fast, well-scoped subagents go on haiku. Subagents doing serious reasoning go on sonnet or opus. Don’t default everything to opus – a search agent burning opus tokens to grep a directory is wasted money.

Tool scoping

The tools allowlist is one of the most useful safety boundaries in Claude Code. A few patterns:

Read-only research subagent:

tools:
  - Read
  - Grep
  - Glob
  - WebFetch
  - WebSearch

Test runner:

tools:
  - Read
  - Bash

File-editor with no shell:

tools:
  - Read
  - Edit
  - Write

If you omit tools, the subagent inherits the full tool set of the parent. For anything you’d let loose on automatic delegation, prefer an explicit allowlist – you don’t want a research subagent that “shouldn’t” run Bash to accidentally have permission to.

Configuration via the Library tab vs editing files directly

Both work. The trade-offs:

Library tab. Changes take effect immediately in the running session. Good for iterating on a description until automatic delegation actually picks it up. Good for one-off user-level subagents.

Direct file edits. Required when you want the subagent definition checked into git (drop it in .claude/agents/ under the project root). Edits on disk are loaded at session start, so a session that was already running needs a restart to pick them up. The Library tab doesn’t have that lag.

For team-shared subagents, define them in .claude/agents/ so every clone of the repo gets the same Library. For your personal helpers, ~/.claude/agents/ keeps them out of the project’s commit history.

Use cases worth wiring up

Changelog writer. Triggered before every commit, drafts the changelog file in your project’s convention. Pairs well with a project rule like “always write the changelog first, then commit.”

Code reviewer. Read-only, runs on opus. Description: “When asked to review a diff or PR, walk the changes and report on correctness, test coverage, security issues, and style violations.” Invoked with @reviewer after staging changes.

Test fixer. Tools: Read, Edit, Bash. Description: “When a test is failing, isolate the failure, propose the minimum fix, run the test, iterate until green.” Pairs naturally with the /goal command.

Doc generator. Reads a module file and produces Markdown docs in asset/docs/. Tools: Read, Write, Grep. Description includes the project’s documentation conventions so the output lands in the right house style.

Migration scout. Read-only, runs on haiku. Description: “Given a library or framework migration objective, scan the codebase and produce a punch list of every file that references the old API.” A cheap way to scope a migration before kicking off the work.

Security reviewer. Tools: Read, Grep, WebFetch. System prompt focused on the OWASP top 10 and your project’s specific threat model.

The common shape: narrow description, narrow tool list, system prompt that captures whatever convention or rule you want enforced consistently. Subagents are the cheap, reusable place to put project rules that would otherwise live in CLAUDE.md as an instruction Claude has to re-read on every turn.

Limits and gotchas

A few constraints worth knowing before you build heavy on this:

When to reach for /agents

Use it when:

Skip it when:

The smallest useful subagent is a 5-line frontmatter and a 3-sentence system prompt with a tight tool list. Start there, not with a 200-line prompt.