Skip to content

Feature Request: Support custom agents defined in .claude/agents/ directory #18212

New issue
New issue
Closed as not planned
Closed as not planned
Feature Request: Support custom agents defined in .claude/agents/ directory#18212
Labels
staleIssue is inactive

Description

@Asifkhan83
Asifkhan83
opened on Jan 14, 2026

Summary

Add support for custom agent definitions in the .claude/agents/ directory, allowing users to define reusable subagents that can be invoked via the Task tool.

Problem

Currently, the Task tool only supports built-in subagent types:

  • Bash
  • general-purpose
  • Explore
  • Plan
  • claude-code-guide
  • statusline-setup

When attempting to use a custom agent defined in .claude/agents/:

Task(
  subagent_type: "logic-designer",  # Custom agent name
  prompt: "..."
)

The error returned is:

Agent type 'logic-designer' not found. Available agents: Bash, general-purpose, statusline-setup, Explore, Plan, claude-code-guide

Current State

Users can create agent definition files in .claude/agents/ with proper frontmatter:

---
name: logic-designer
description: Design evaluation logic using P+Q+P framework
allowed-tools: Read, Glob, Grep, AskUserQuestion
---

# Agent Instructions
...

However, these custom agents are not recognized by the Task tool.

Proposed Solution

  1. Scan .claude/agents/ directory on startup for *.md files
  2. Parse frontmatter to extract:
    • name - Agent identifier for subagent_type
    • description - Shown in agent listings
    • allowed-tools - Restrict tool access for the agent
  3. Register custom agents alongside built-in agents
  4. Inject agent instructions as system context when the agent is spawned

Expected Behavior

# Should work after implementation
Task(
  subagent_type: "logic-designer",  # Matches 'name' in frontmatter
  prompt: "Design a calculator parser"
)

The agent would:

  • Have access only to tools specified in allowed-tools
  • Receive the markdown content as its system instructions
  • Be listed in available agents

Use Cases

  1. Domain-specific agents - Create specialized agents for specific frameworks/languages
  2. Team standardization - Share agent definitions across projects
  3. Workflow automation - Define agents for common multi-step tasks
  4. P+Q+P Framework agents - Agents that follow specific reasoning patterns

Workaround

Currently using general-purpose agent with full instructions injected into the prompt, but this:

  • Doesn't respect allowed-tools restrictions
  • Requires copying full agent content each time
  • Loses the reusability benefit

Environment

  • Claude Code CLI
  • Custom agents in .claude/agents/*.md

Related

This would complement the existing .claude/skills/ functionality, providing a complete extensibility model:

  • Skills - For simple, template-based operations
  • Agents - For complex, reasoning-heavy tasks requiring multiple decisions

Activity

  1. jschulte commented on Jan 30, 2026

    @jschulte
    jschulte
    on Jan 30, 2026

    Real-World Use Case: BMAD Method Multi-Agent Orchestration

    I'm a heavy user of BMAD-METHOD, an open-source framework for AI-assisted software development that uses specialized agent personas for different workflow phases. This feature would be transformational for BMAD users.

    Current Pain Point

    BMAD defines 10+ specialized agents with distinct personas, expertise, and communication styles:

    • dev - Implementation specialist with TDD discipline
    • architect - System design and technical decisions
    • analyst - Requirements analysis and market research
    • tea (Test Architect) - Test strategy and quality validation
    • pm - Product management and prioritization
    • sm - Sprint coordination and workflow management

    These agents are registered as Skills via .claude/commands/bmad_*.md launchers and work perfectly in the main conversation. However, our multi-agent workflows need to spawn these as background Task agents for parallel execution.

    What's Blocked

    Example workflow (story-pipeline):

    agents:
  builder:
    subagent_type: "dev"        # ❌ FAILS - not recognized
    prompt_file: "{agents_path}/builder.md"
  reviewer:
    subagent_type: "architect"  # ❌ FAILS - not recognized

    Workaround required:

    agents:
  builder:
    subagent_type: "general-purpose"  # ✅ Works but loses persona
    prompt_file: "{agents_path}/builder.md"

    Using general-purpose means:

    • Lost agent specialization (TDD discipline, design principles, communication style)
    • Prompt bloat from re-injecting full persona every time
    • No reusability across workflows
    • Users can't leverage their investment in custom agent design

    Concrete Impact

    1. Parallel research blocked - Can't run analyst market research + architect technical research simultaneously with specialized personas
    2. Review quality degraded - tea agent's testing expertise isn't available in background validation tasks
    3. Workflow orchestration broken - Workflows declare specialized agents but spawn generic ones

    Proposed Solution Alignment

    Your proposed .claude/agents/ directory approach would solve this perfectly. Our agents are already defined in a compatible format:

    # _bmad/bmm/agents/dev.md
---
name: dev
role: Senior Software Engineer
identity: Executes approved stories with TDD discipline...
---
[Full agent activation instructions]

    If Task tool could discover and spawn these as subagent_type: "dev", it would:

    • Enable true multi-agent orchestration
    • Preserve agent specialization in background tasks
    • Allow framework authors to define reusable agent libraries

    Supporting Evidence

    We just hit this exact error today:

    Error: Agent type 'bmad_bse_agent_builder' not found. Available agents: 
Bash, general-purpose, statusline-setup, Explore, Plan, claude-code-guide...

    The agent tried to spawn a BMAD agent as a Task subagent, which is the intuitive behavior users expect.

    Would love to help test this feature if there's a beta or experimental flag. Happy to provide additional use cases from the BMAD community.

  2. github-actions
    added
    staleIssue is inactive
    on Feb 14, 2026

  3. github-actions commented on Feb 28, 2026

    @github-actions
    github-actionsBot
    on Feb 28, 2026 – with GitHub Actions

    Closing for now — inactive for too long. Please open a new issue if this is still relevant.

  4. github-actions
    closed this as not plannedon Feb 28, 2026

  5. github-actions commented on Mar 7, 2026

    @github-actions
    github-actionsBot
    on Mar 7, 2026 – with GitHub Actions

    This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

  6. github-actions
    locked as resolved and limited conversation to collaborators on Mar 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    staleIssue is inactive

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions