Custom agents from ~/.claude/agents/ cannot be invoked as Task subagents

Resolved 💬 2 comments Opened Feb 13, 2026 by oesteban Closed Feb 13, 2026

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

  1. Create a custom agent file at ~/.claude/agents/my-agent.md with valid frontmatter (iname, description, model, etc.)
  2. In a conversation, attempt to invoke it via the Task tool with subagent_type: "my-agent"
  3. 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-purpose agent 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.md with iname: nipreps-guru

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗