[BUG] Custom Agents in ~/.claude/agents/ Not Loaded as Task Subagent Types
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
What's Wrong?
Environment:
- OS: macOS Darwin 25.2.0
- Claude Code Version: [Your version - check with
claude --version] - Working Directory: /Users/insu/code/pyright-mcp-server
Summary:
Custom agents placed in ~/.claude/agents/ are not discovered or loaded at session start, making them unavailable for Task(agent-name, "...") invocations. The error message
states the agent "isn't available as a built-in Task subagent type."
Expected Behavior:
Custom agents defined in ~/.claude/agents/*.md should be:
- Discovered and loaded at session start
- Available for invocation via
Task(agent-name, "...") - Persist across sessions
Actual Behavior:
- Custom agent files are completely ignored
Task(coordinator, "...")fails with error: "coordinator agent isn't available as a built-in Task subagent type"- Only built-in agents (Explore, Plan, general-purpose) and UI-created agents work
- UI-created agents disappear after session restart
Evidence:
### 1. Agent File Exists and Is Valid
```bash
$ ls -lh ~/.claude/agents/coordinator.md
-rw-r--r-- 1 insu staff 99KB Jan 26 15:20 ~/.claude/agents/coordinator.md
$ head -20 ~/.claude/agents/coordinator.md
---
# Agent Identity
name: coordinator
slug: coordinator
model: haiku
tier: haiku
version: "2.0"
# AI-OD Capability Declaration
capabilities:
strengths:
- "DAG plan execution and orchestration"
- "Task dispatch and worker coordination"
...
- Referenced in Configuration Files
# routing.yaml (lines 101-106)
$ grep -A5 "coordinator:" ~/.claude/config/routing.yaml
coordinator:
tier: haiku
model: haiku
delegates_to: [all workers]
description: "Plan execution and orchestration"
# autonomy.yaml (lines 192-194)
$ grep -A2 "coordinator:" ~/.claude/config/autonomy.yaml
coordinator:
always_supervised: false
auto_execute_threshold: 0.85
- Never Appears in Metrics
$ grep '"subagent_type": "coordinator"' ~/.claude/metrics/sessions/*.jsonl
# Returns nothing - coordinator has NEVER been invoked
# Compare with other agents that DO work:
$ grep -o '"subagent_type": "[^"]"' ~/.claude/metrics/sessions/.jsonl | sort | uniq -c
12 "subagent_type": "Explore"
8 "subagent_type": "Plan"
6 "subagent_type": "git-ops"
4 "subagent_type": "delegation-guide-manager"
3 "subagent_type": "dba"
- Other Custom Agents Also Fail
The issue affects ALL file-based custom agents:
- coordinator.md (2,853 lines)
- analyst.md (exists, never loaded)
- Multiple other .md files in ~/.claude/agents/
Impact:
- HIGH: Completely breaks custom agent functionality
- Users cannot create reusable specialized agents via file definitions
- Forces reliance on UI-created agents that don't persist
- Documented agent system unusable
Workarounds:
- Use built-in agents (Explore, Plan, general-purpose)
- Recreate agents via /agents UI each session (session-scoped only)
- Use Task(thinker, "MODE: plan") as replacement for coordinator
Additional Context:
- settings.json is valid JSON
- Hooks system works correctly (SessionStart hooks execute)
- Commands/skills load properly from ~/.claude/commands/
- Only agent file discovery is broken
Related Issues:
This may be related to earlier reports about agent discovery (#11205 if it exists).
Requested Fix:
Either:
- Fix file discovery: Scan ~/.claude/agents/*.md at session start and register agents
- Document limitation: Clarify that file-based agents aren't supported
- Add diagnostics: Provide /agents debug command to show why agents fail to load
Files for Review:
- ~/.claude/agents/coordinator.md (full agent definition)
- ~/.claude/config/routing.yaml (agent routing configuration)
- Session logs showing Task() invocation failure
Happy to provide additional diagnostics or test fixes.
What Should Happen?
Custom agents defined in ~/.claude/agents/*.md should be:
- Discovered and loaded at session start
- Available for invocation via
Task(agent-name, "...") - Persist across sessions
Error Messages/Logs
⏺ coordinator(Execute Phase 2.5 hardening plan)
⎿ Initializing…
⎿ Error: Agent type 'coordinator' not found. Available agents: Bash, general-purpose, statusline-setup, Explore, Plan, claude-code-guide, architect, web-fetcher, maestro,
thinker, guide-manager, orchestrator, pyright-specialist
claude-code-guide(Investigate why coordinator not loadable)
⎿ Done (12 tool uses · 42.4k tokens · 50s)
⎿ Running PostToolUse hooks… (1/2 done)
⏺ Investigation Complete: Root Cause Found
I've identified why the coordinator agent isn't loading. This is a known bug in Claude Code's agent discovery system.
---
The Problem
Your coordinator.md file is perfect - correctly placed, valid YAML frontmatter, proper structure. But Claude Code has a broken file discovery mechanism that ignores custom
agents in ~/.claude/agents/.
Evidence
1. coordinator.md exists and is valid (confirmed earlier - 2,853 lines, proper frontmatter)
2. Listed in routing.yaml (lines 101-106)
3. But NEVER appears in metrics - No "subagent_type": "coordinator" in any session
4. Other agents work - git-ops, delegation-guide-manager show up in metrics
Why This Happens
Claude Code uses two discovery mechanisms:
┌────────────────────────────────────┬───────────┬────────────────────────┐
│ Method │ Status │ Agents Available │
├────────────────────────────────────┼───────────┼────────────────────────┤
│ File-based (~/.claude/agents/*.md) │ 🔴 BROKEN │ None (files ignored) │
├────────────────────────────────────┼───────────┼────────────────────────┤
│ UI-created (/agents command) │ ✅ WORKS │ Session only │
├────────────────────────────────────┼───────────┼────────────────────────┤
│ Built-in │ ✅ WORKS │ Always (Explore, Plan) │
└────────────────────────────────────┴───────────┴────────────────────────┘
When you call Task(coordinator, "..."), Claude Code checks its loaded agents registry. Since file discovery is broken, coordinator never gets registered.Steps to Reproduce
- Create a custom agent file:
cat > ~/.claude/agents/test-agent.md << 'EOF'
---
name: test-agent
slug: test-agent
model: haiku
tools:
required: ["Read"]
---
# Test Agent
You are a test agent for reproduction.
EOF
- Start a new Claude Code session:
claude
- Try to invoke the agent:
Task(test-agent, "test invocation")
- Observe error: "test-agent agent isn't available as a built-in Task subagent type"
- Verify file is ignored:
grep '"subagent_type": "test-agent"' ~/.claude/metrics/sessions/*.jsonl
# Returns nothing
Claude Model
Sonnet (default)
Is this a regression?
I don't know
Last Working Version
_No response_
Claude Code Version
2.1.19 (Claude Code)
Platform
Anthropic API
Operating System
macOS
Terminal/Shell
Terminal.app (macOS)
Additional Information
_No response_
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗