Custom agents from ~/.claude/agents/ cannot be invoked as Task subagents
Description
Custom agents defined in ~/.claude/agents/*.md cannot be spawned via the Task tool's subagent_type parameter. The Task tool only accepts a hardcoded set of built-in agent types (Bash, general-purpose, Explore, Plan, claude-code-guide, statusline-setup, yoda-analysis-setup).
Steps to Reproduce
- Create a custom agent file at
~/.claude/agents/my-agent.mdwith valid frontmatter (iname,description,model, etc.) - In a conversation, attempt to invoke it via the Task tool with
subagent_type: "my-agent" - Error returned:
Agent type 'my-agent' not found. Available agents: Bash, general-purpose, statusline-setup, Explore, Plan, claude-code-guide, yoda-analysis-setup
Expected Behavior
Custom agents defined in ~/.claude/agents/ should be discoverable and invocable as Task subagent types, allowing the main conversation to delegate specialized work to user-defined agents (just as it can to built-in ones).
Context
This is a meaningful gap because custom agents are designed to encapsulate domain expertise (e.g., a "NiPreps Guru" agent for neuroimaging workflow architecture). Being able to spawn them as subagents from a main coding session -- rather than only at the top-level conversation -- would enable powerful compositional workflows where domain experts are consulted mid-task.
Workarounds Attempted
- Passing the custom agent name as
subagent_type→ error (as described) - Using
/agent <name>as a skill → "Unknown skill: agent" - Using a
general-purposeagent with the custom agent's system prompt pasted in → works but loses the agent's persistent memory, model preferences, and identity
Environment
- Claude Code CLI
- Custom agent file:
~/.claude/agents/nipreps-guru.mdwithiname: nipreps-guru
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗