{"slug": "claude-code-subagents-how-claude-agents-files-work-and-why-claude-never-uses", "title": "Claude Code subagents: how .claude/agents files work, and why Claude never uses yours", "summary": "Claude Code's subagent system relies on Markdown files with YAML frontmatter, where the description field acts as the routing trigger for delegation. Developers often face issues due to poorly written descriptions, name collisions, and invalid tool entries, which can silently drop or prevent agents from launching. Properly structured descriptions that specify when to delegate, along with valid tool names and unique lowercase names, ensure subagents function as intended.", "body_md": "Claude Code lets you define your own subagents — Markdown files that give Claude a specialist it can delegate to, with its own system prompt, its own tool access, and its own context window. The mechanism is simple, but most \"my subagent doesn't work\" problems come from three details the docs mention once and people skim past: the `description`\n\nfield is the router, `name`\n\ncollisions silently drop a file, and one bad `tools`\n\nentry stops the agent from launching at all.\n\nHere's the whole system, verified against the current docs.\n\nA subagent is one Markdown file with YAML frontmatter:\n\n```\n---\nname: code-improver\ndescription: \"Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.\"\ntools: Read, Grep, Glob\nmodel: sonnet\n---\n\nYou are a code review specialist. When given files, analyze them for\nreadability, performance, and adherence to best practices. Report\nconcrete, minimal suggestions with file:line references.\n```\n\nWhere you put it decides who gets it:\n\n`.claude/agents/`\n\nin your project → this project (usually committed, so your team shares it)`~/.claude/agents/`\n\n→ every project on your machineBoth locations are scanned recursively, so you can organize files into subfolders like `agents/review/`\n\n. The subfolder path changes nothing about how the agent is identified — identity comes only from the `name`\n\nfield, not the filename or path.\n\nOnly `name`\n\nand `description`\n\nare required. Everything else is optional.\n\nClaude reads every subagent's `description`\n\nand decides to delegate when a task matches it. That's the entire routing mechanism. There is no registration step, no config toggle — the quality of your `description`\n\n*is* the trigger.\n\nWhich means the most common failure is writing a description like a title:\n\n```\n# never gets used\ndescription: Database expert\n\n# gets used\ndescription: Reviews SQL queries and schema changes for slow patterns,\n  missing indexes, and migration risks. Use when SQL or migration files change.\n```\n\nThe second one works because it describes *when* to delegate, not just what the agent is. If you want delegation to happen without being asked, say so in the description — phrasing like \"use proactively after code changes\" is exactly what the official examples do.\n\nYou can always bypass routing and invoke one explicitly: \"Use the code-improver subagent on the files I just changed.\"\n\nThe full frontmatter list is longer, but these are the ones I reach for:\n\n| Field | What it does |\n|---|---|\n`tools` |\nAllowlist. Omit it and the agent inherits every tool available to subagents. |\n`disallowedTools` |\nDenylist, subtracted from the inherited or specified list. |\n`model` |\n`sonnet` , `opus` , `haiku` , a full model ID, or `inherit` (the default). |\n`maxTurns` |\nHard cap on agentic turns before the subagent stops. |\n`skills` |\nSkills preloaded into the subagent's context at startup — full content, not just the description. |\n`memory` |\n`user` , `project` , or `local` — gives the agent persistent memory across sessions. |\n`background` |\n`true` forces background execution. Left unset, Claude chooses (and current versions default to background). |\n`isolation` |\n`worktree` runs the agent in a temporary git worktree so its edits can't collide with yours. |\n\nTwo sharp edges in `tools`\n\n: the entries must resolve to real tool names — if none of them do, the subagent fails to launch with an error naming the bad entries. And if you want a Skill preloaded, use the `skills`\n\nfield; listing `Skill`\n\nin `tools`\n\nonly grants the invocation tool, it doesn't load anything.\n\nOne sharp edge in `name`\n\n: lowercase letters and hyphens, and no `:`\n\n— colons are reserved for plugin-scoped identifiers like `my-plugin:reviewer`\n\n. Current versions refuse to load a file whose name contains one, and the only symptom is a line in the debug log.\n\nWhen multiple subagents share a name, the higher-priority location wins: managed (organization-deployed) definitions beat project definitions, which beat user definitions, which beat plugin agents. Across nested project directories, the definition closest to your working directory wins.\n\nThe dangerous case is two files with the same `name`\n\nunder the *same* `.claude/agents/`\n\ntree — including subfolders. Claude Code loads only one, chosen by filesystem read order, not by any documented rule. Nothing warns you at runtime; your carefully updated definition may simply not be the one running. `/doctor`\n\nreports same-directory duplicates, so run it whenever a subagent behaves like an older version of itself.\n\nAlso worth knowing: a project or user subagent named `Explore`\n\noverrides the built-in read-only Explore agent. That's occasionally useful (for example, pinning exploration to a cheaper model with `model: haiku`\n\n) — and occasionally an accident, when someone names a general agent \"explore\" and quietly replaces the built-in.\n\nOlder writeups tell you to run `/agents`\n\nfor an interactive creation wizard. That wizard is gone in current versions — `/agents`\n\nnow just points you at editing `.claude/agents/`\n\ndirectly, or you ask Claude to write the file for you. The file format and locations didn't change, so any existing agent files keep working.\n\nWhen a subagent isn't being used, this order finds it fastest:\n\n`name`\n\nanywhere in the tree → run `/doctor`\n\n.`tools`\n\nentries resolve?`Greps`\n\nfails the launch with a zero-tools error.*I publish daily practical notes on Claude Code, Cursor, and Codex on Bluesky — @ai-shop.bsky.social. The tested skill and rules packs I maintain live at Rulestack.*", "url": "https://wpnews.pro/news/claude-code-subagents-how-claude-agents-files-work-and-why-claude-never-uses", "canonical_source": "https://dev.to/rulestack/claude-code-subagents-how-claudeagents-files-work-and-why-claude-never-uses-yours-31bl", "published_at": "2026-08-04 01:00:20+00:00", "updated_at": "2026-08-04 01:39:05.732275+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models"], "entities": ["Claude Code", "Anthropic"], "alternates": {"html": "https://wpnews.pro/news/claude-code-subagents-how-claude-agents-files-work-and-why-claude-never-uses", "markdown": "https://wpnews.pro/news/claude-code-subagents-how-claude-agents-files-work-and-why-claude-never-uses.md", "text": "https://wpnews.pro/news/claude-code-subagents-how-claude-agents-files-work-and-why-claude-never-uses.txt", "jsonld": "https://wpnews.pro/news/claude-code-subagents-how-claude-agents-files-work-and-why-claude-never-uses.jsonld"}}