# Custom subagents in Claude Code > Create a specialist agent with explicit instructions and limited tool access. Page: https://videotomd.com/b/e18sdZLwP7o/ Tool: Claude Code · Tags: subagents · 452 words, about 588 tokens Pills: free · checked 2026-10-15 · Claude Code · file tools · shell · on demand · frontier · coding · starting out · building ## Recipe - Kind: workflow - Stage: starting out, building - Loads: on demand - Works in: Claude Code - Needs: file tools, shell - Bring: nothing - Cost: free - Model: frontier - Tested in: not yet - Checked: 2026-10-15 - For: coding ## Similar - [Claude Code skills](https://videotomd.com/b/bjdBVZa66oU/): Pick a skill when you want reusable instructions loaded into the main conversation, with no separate context window and no tool restriction. - [Claude Code hooks](https://videotomd.com/b/IkaPHiMDazM/): Pick hooks when a rule must be enforced every time, such as blocking dangerous commands, rather than relying on one agent's tools list. ## Put it here Loads on demand: paste or attach it when the task comes up. To have it every session, put it where your tool reads instructions: - Claude Code: Save as CLAUDE.md in the project root, or .claude/CLAUDE.md. Other agents share the repo: put the shared rules in AGENTS.md and make CLAUDE.md one line, @AGENTS.md. Commit it. Start a new session: the file is read at launch. Reload: new session (or /memory to open the files). Check it loaded: /context lists the Memory files it read; /skills, /agents, /hooks list the rest; the InstructionsLoaded hook event fires once per loaded instruction file. Source: https://code.claude.com/docs/en/memory (checked 2026-10-12). ## Access Free, no signup. The complete file follows. --- # Custom subagents in Claude Code ## Before you start - Needs: Claude Code and a bounded task for a specialist. ## Steps 1. Ask Claude to create the agent file, or write it yourself: `.claude/agents/.md` for this project, `~/.claude/agents/.md` for all your projects. `/agents` only prints this reminder; its wizard ended with Claude Code v2.1.197. 2. In the frontmatter set `name`, a specific trigger `description`, `model` and the `tools` it may use; the body is its instructions. A read-only reviewer gets `tools: Read, Grep, Glob` and no Bash, Edit or Write. 3. Inspect the file; fix malformed YAML. If the `agents` folder is new since the session started, restart Claude Code so it is found. 4. Ask Claude to use the named agent on a sample task. Verify its output and tool access. ## Your steps A guide, not a guarantee: a recipe is better with your own steps in it. Add what you changed and why below; your AI keeps this section with the recipe and reads it first next time. - (your first change, and why) ## Warnings - Parallel agents consume additional usage. - If you leave the tools field out, the subagent gets every tool the main conversation has, including Bash, Edit and Write, so a missing line silently undoes the read-only setup. - A user or project agent named Explore, or any other built-in name, replaces that built-in agent and keeps its own model, so a careless name changes how Claude searches the codebase. ## Harden - Keep description to one trigger sentence and put the detail in the body. Every description sits in the main context, and custom descriptions that add up to more than 15,000 tokens trigger a startup warning. Costs: A short trigger gets picked automatically less often, so you will name the agent in your prompt more. - Set model: haiku on read-only search or review agents so routine delegation does not burn your main usage limits. Costs: Runs are cheaper and faster but reason less deeply, so a haiku reviewer can miss subtle bugs that the main model would catch. - If an agent needs Bash, add hooks in its subagent frontmatter that block destructive commands for that agent only, instead of trusting its instructions. Costs: That is one more hook script to maintain, and a loose matcher blocks legitimate commands and stalls the agent mid-task. ## Similar - [Claude Code skills](https://videotomd.com/b/bjdBVZa66oU/): Pick a skill when you want reusable instructions loaded into the main conversation, with no separate context window and no tool restriction. - [Claude Code hooks](https://videotomd.com/b/IkaPHiMDazM/): Pick hooks when a rule must be enforced every time, such as blocking dangerous commands, rather than relying on one agent's tools list.