Creating Your First Subagent with /agents
The /agents Command
The easiest way to create and manage subagents is the /agents slash command. It opens a tabbed interface: a Running tab showing live subagents (which you can open or stop), and a Library tab where you view, create, edit, and delete subagents. The Library lists every available subagent — built-in, user, project, and plugin — and shows which is active when duplicates exist.
Why use the UI over hand-editing files?
Subagents created through /agents take effect immediately. Subagents you add by editing files on disk are only loaded at session start, so they need a restart. For a fast create-test loop, /agents is the recommended path.
The Creation Flow
Creating a subagent walks through a short series of choices. The recommended approach is 'Generate with Claude': you describe what you want the subagent to do, and Claude produces the identifier, description, and system prompt for you.
The /agents creation flow: choose scope, generate with Claude, pick tools, model, and color, then save.
A Walkthrough: A Code-Improvement Subagent
Suppose you want a read-only agent that scans files and suggests improvements. In /agents you'd: switch to the Library tab → Create new agent → choose Personal (saves to ~/.claude/agents/, available in all projects). Then Generate with Claude, describing it:
A code improvement agent that scans files and suggests improvements
for readability, performance, and best practices. It should explain
each issue, show the current code, and provide an improved version.Next you deselect everything except read-only tools (a reviewer shouldn't edit), pick Sonnet (good balance for analyzing code patterns), choose a color, optionally enable persistent memory, then save. The subagent is available immediately — try it with: 'Use the code-improver agent to suggest improvements in this project.'
Generate, then refine
Letting Claude generate the first draft is faster than writing config by hand, and you can always edit the result. Treat the generated description and system prompt as a strong starting point you then sharpen.
Other Ways to Create Subagents
The /agents UI is recommended, but it isn't the only path. Subagents are ultimately just files (or JSON), so you can create them several ways depending on your need:
- •/agents interface — guided, immediate, recommended for most cases.
- •Manual Markdown files — write .claude/agents/name.md yourself (needs a restart to load).
- •CLI flag — pass JSON via --agents when launching Claude Code, for a session-only subagent (great for testing/automation).
- •Plugins — distribute subagents to a whole team via a plugin's agents/ directory.
Next
You've created a subagent. Next we open up the file it produced — the YAML frontmatter and system prompt — so you understand and can hand-edit every field.
Key Takeaways
- ✓The /agents command opens a tabbed UI (Running + Library) to view, create, edit, and delete subagents — the recommended path.
- ✓Subagents made via /agents take effect immediately; hand-edited files load only at session start (need a restart).
- ✓The creation flow: choose scope (project/user) → Generate with Claude → pick tools → pick model → pick color → save.
- ✓'Generate with Claude' produces the name, description, and system prompt from a plain-language description you provide.
- ✓A read-only reviewer should keep only read-only tools and can use Sonnet for balanced code analysis.
- ✓Beyond the UI you can create subagents via manual Markdown files, the --agents CLI flag (session-only), or plugins (team distribution).
Check Your Understanding
Test what you learned in this lesson.
Q1.What is the recommended way to create and manage subagents?
Q2.Why might a subagent you created by editing a file on disk not appear right away?
Q3.In the creation flow, what does 'Generate with Claude' produce from your description?
Q4.Which method creates a session-only subagent that isn't saved to disk?
Practice This Lesson