Feature Request: Support subdirectories for agent organization (like Skills)

🎯 Feature Request: Subdirectory Support for Agents

Summary

Support organizing Agents in subdirectories (e.g., agents/development/code-reviewer.md), similar to how Skills already support subdirectories (e.g., skills/development/code-review/SKILL.md).

📊 Current State

| Feature | Subdirectory Support | Example Structure |
|---------|---------------------|-------------------|
| Skills | ✅ Yes | skills/{category}/{skill-name}/SKILL.md |
| Agents | ❌ No | agents/{agent-name}.md (flat only) |

📝 Current Behavior

Agents must be placed directly in ~/.claude/agents/ or .claude/agents/:

~/.claude/agents/
├── coder.md
├── mcp-doctor.md
├── gsd-planner.md
├── gsd-executor.md
├── gsd-verifier.md
├── codebase-analyst.md
├── playwright-test-planner.md
├── playwright-test-generator.md
├── security-scanner.md
... (34+ agents in flat structure)

🎯 Desired Behavior

Agents should support subdirectories for better organization:

~/.claude/agents/
├── development/
│   ├── coder.md
│   ├── codebase-analyst.md
│   └── spec-compliance-coach.md
├── testing/
│   ├── playwright-test-planner.md
│   ├── playwright-test-generator.md
│   └── e2e-behavior-simulator.md
├── security/
│   ├── security-scanner.md
│   ├── db-migration-validator.md
│   └── accessibility-auditor.md
├── infrastructure/
│   ├── mcp-doctor.md
│   └── daily-summary-agent.md
└── gsd/
    ├── gsd-planner.md
    ├── gsd-executor.md
    ├── gsd-verifier.md
    └── gsd-debugger.md

💡 Use Cases

1. Large Agent Libraries: Projects with 30+ agents become difficult to navigate
2. Team Collaboration: Different teams can maintain their own agent categories
3. Logical Grouping: Group agents by domain (development, testing, security, infrastructure)
4. Consistency: Aligns agent organization with existing skill organization patterns

🔍 Reference: Skills Already Support This

From skills.md documentation:

"Structure multi-file Skills with detailed documentation in separate files" `` my-skill/ ├── SKILL.md (required - overview and navigation) ├── reference.md (detailed API docs) └── examples.md ``

✅ Proposed Implementation

1. Recursive Discovery: Scan agent directories recursively (like skills)
2. Flat Namespace: Agent name in YAML frontmatter remains unique identifier
3. Backward Compatible: Existing flat structure continues to work
4. Priority Order: Same as skills (Enterprise > Personal > Project > Plugin)

📄 Example Agent in Subdirectory

File: ~/.claude/agents/development/coder.md

---
name: coder
description: Implementation specialist for writing code based on specifications
tools: All tools
model: sonnet
---

You are a coder agent specializing in implementing features...

Invocation (unchanged):

Use the coder agent to implement feature X
Task("coder", "implement this feature")

🎯 Benefits

• ✅ Scalability: Supports 100+ agents without clutter
• ✅ Consistency: Matches skill organization pattern
• ✅ Backward Compatible: No breaking changes
• ✅ Developer Experience: Easier navigation and maintenance

🔧 Minimal Implementation

1. Modify agent discovery to use recursive directory scan (glob pattern: **/*.md)
2. Update documentation to reflect subdirectory support
3. Add examples showing categorized agent structures

---

Version: Claude Code CLI
Priority: Medium (quality-of-life improvement)
Breaking Changes: None (backward compatible)