Custom agents in .claude/agents/ not discovered by /agents command or Task tool (v2.0.50)

Description

Custom agents placed in .claude/agents/ are not being discovered by Claude Code. Neither the /agents slash command nor the Task tool can find user-defined agents.

Environment

• Claude Code version: 2.0.50
• OS: macOS Darwin 24.6.0
• Platform: darwin

Steps to Reproduce

1. Create .claude/agents/ directory in project root
2. Create a minimal agent file .claude/agents/test-agent.md:

```yaml
---
name: test-agent
description: Minimal test agent for debugging discovery
---

Test agent content.
```

1. Run /agents command
2. Observe: "no agents configured"
3. Try to invoke via Task tool - only built-in agents available (general-purpose, Explore, Plan, claude-code-guide, statusline-setup)

Expected Behavior

• /agents should list custom agents from .claude/agents/
• Task tool should be able to spawn custom agents by name

Actual Behavior

• /agents shows "no agents configured"
• Task tool returns: Agent type 'test-agent' not found. Available agents: general-purpose, statusline-setup, Explore, Plan, claude-code-guide

Troubleshooting Attempted

• ✅ Verified YAML frontmatter is valid (proper --- delimiters, required fields present)
• ✅ Checked file encoding (clean UTF-8/ASCII, no BOM)
• ✅ Verified no hidden characters or trailing spaces
• ✅ Fixed file permissions to 644
• ✅ Confirmed TMPDIR is not set (not the cause)
• ✅ Tested with minimal agent file (still not discovered)
• ✅ Tested both project-level (.claude/agents/) and user-level (~/.claude/agents/) directories

Agent File Examples

All agents have valid frontmatter following the documented format:

---
name: dev-architect
description:
  Analyzes PRDs and feature requests to produce engineering specifications.
  Decomposes into independent systems, delegates to sub-architects in parallel,
  then assembles the complete specification.
tools: AskUserQuestion, Bash, Glob, Grep, Read, Skill, Task, WebFetch, WebSearch
model: sonnet
color: magenta
---

Possibly Related Issues

• #4626 - Custom agents not detected
• #4773 - Project-local agents not discovered
• #5185 - Custom agents not appearing despite valid YAML
• #10194 - TMPDIR bug causing silent failures

Additional Context

The agent discovery mechanism appears to be completely non-functional for custom agents in v2.0.50. Built-in agents work fine, but user-defined agents in .claude/agents/ are never loaded.

🤖 Generated with Claude Code