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

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

1. Register custom agents alongside built-in agents
2. 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