← Blog · 2026-10-17

Claude Code Subagent Not Being Used? 10 Reasons It's Skipped or Ignored

Shortcut: our free subagent builder writes a valid .claude/agents/<name>.md file (and the --agents JSON) with the name rules already applied, so the "skipped silently" problems below can't happen. It runs in your browser.

A subagent is a Markdown file in .claude/agents/ (one project) or ~/.claude/agents/ (every project). The YAML at the top tells Claude Code its name, its description, and optionally which tools and model it gets. The text below is its system prompt. When a request matches the description, Claude hands the task to that subagent, which works in its own context window and reports back.

There are two very different ways this goes wrong. Either Claude Code never loaded the file, or it loaded it and Claude just doesn't pick it. The fixes are different, so figure out which one you have first.

First: is it loaded at all?

Type @ in Claude Code and look for your subagent in the typeahead. If yours isn't there, start at reason 1. If it's there but Claude does the work itself, skip to reason 6.

Not loaded: 5 reasons Claude Code skips the file

Claude Code skips a broken agent file without saying anything in the session. These are the cases Anthropic's docs list:

1. The agents folder didn't exist when the session started. Claude Code watches ~/.claude/agents/ and .claude/agents/ and picks up new or edited files within a few seconds, with no restart. But it only watches folders that existed at startup. If you just created the folder along with your first agent, restart Claude Code.
2. There's no name, or the --- isn't on line 1. A file without a name is treated as documentation. So is a file where anything, even a blank line, comes before the opening ---.
3. The name breaks a rule. A name that starts with -, contains a :, or is longer than 256 characters is skipped. Stick to lowercase letters and hyphens, like client-report-writer.
4. There's a name but no description. Both are required. Only those two are.
5. The YAML doesn't parse. One stray colon in an unquoted description is enough. Claude Code then reads no fields from the file at all. Put descriptions with colons in quotes.

To see why a file was skipped, start Claude Code with claude --debug; the reason goes to the debug log. You can also run claude plugin validate .claude/agents (or ~/.claude/agents) to find files whose frontmatter doesn't parse. It won't flag a file that parses but has no name, so check that one by eye.

Two quieter versions of "not loaded":

• A same-named agent wins. If two subagents share a name, the higher-priority location is used: project .claude/agents/ beats your personal ~/.claude/agents/, and an admin-managed one beats both. Two files with the same name in one folder means only one loads, and which one isn't defined. /doctor reports those duplicates.
• It's in an --add-dir folder. Claude Code loads .claude/agents/ from directories you add with --add-dir or /add-dir, but doesn't watch them, so edits there need a restart.

Loaded but ignored: 5 reasons Claude doesn't delegate

6. The description says what it is, not when to use it. Claude decides whether to delegate by reading the description. "Expert writer" gives it nothing to match. "Drafts the monthly client report from my notes. Use when I ask for a client update or monthly summary" does. Write the trigger phrases your requests actually contain.
7. It never says "use proactively". Anthropic's docs say that to encourage automatic delegation, you should put phrases like "use proactively" in the description, for example "Reviews code for quality. Use proactively after code changes."
8. Too many long descriptions. Every subagent's description sits in Claude's context. When your custom ones add up to more than 15,000 tokens, Claude Code warns at startup. Keep each description to a sentence or two and move the detail into the system prompt, which only loads when that subagent runs.
9. It's been denied in settings. A permissions.deny entry like Agent(my-agent) blocks that subagent, and denying Agent on its own stops all delegation. Check your project and user settings.json, and any settings.local.json.
10. Its tools list resolves to nothing. If every entry in tools is a typo (Grpe), a tool subagents can't use, or an MCP tool that isn't connected right now, Claude Code refuses to launch it and shows an error that names the bad entries. Background subagents, which are the default, get a smaller set of built-in tools, so a tool that works in the foreground can drop out. If in doubt, leave tools out: the subagent then inherits the tools available to subagents.

Three ways to make it run anyway

Automatic delegation is Claude's call. When you want a specific subagent, ask for it, from gentlest to firmest:

• Name it in plain words: "Use the client-report-writer subagent to draft this month's update." Claude usually delegates.
• @-mention it: type @ and pick it, or type @agent-client-report-writer. This guarantees that subagent runs for that task.
• Run the whole session as it: start Claude Code with claude --agent client-report-writer, or set the agent setting.

A minimal file that loads

---
name: client-report-writer
description: "Drafts the monthly client report from my notes. Use proactively when I ask for a client update, monthly summary or status report."
tools: Read, Grep, Glob, Write
---
You write monthly client reports for a solo consultant. Read the notes
the user points to, then draft a one-page report: what was done, results,
what's next, and anything needed from the client. Plain language, no jargon.

Save it as .claude/agents/client-report-writer.md, check the typeahead, and try a request that matches the description.

Facts on this page come from Anthropic's subagents documentation and error reference. This guide isn't affiliated with Anthropic.

If you do client work in Claude Code, skills cover the repeat jobs that don't need a separate subagent. Start with our free 3-skill sample (client follow-ups, meeting notes to tasks, invoice chasing), or get the full Solo Consultant Kit.