Custom agents in .claude/agents/ not discovered by /agents dialog (v2.1.89)
Resolved 💬 8 comments Opened Apr 1, 2026 by Cathypark-kor Closed Apr 18, 2026
Bug Description
Custom agent files placed in .claude/agents/ (both project-level and user-level) are not discovered by the /agents dialog or claude agents CLI command.
Environment
- Claude Code version: 2.1.89 (latest as of 2026-04-01)
- OS: macOS (Darwin 24.6.0, ARM64)
Steps to Reproduce
- Create
.claude/agents/directory in project root - Add agent
.mdfiles with valid YAML frontmatter:
``yaml``
---
name: growth-lead
description: "Growth Squad lead agent"
tools: Read, Write, Edit, Grep, Glob, WebSearch, WebFetch
model: opus
---
- Restart Claude Code session
- Run
/agents— shows "No agents found" - Run
claude agentsin terminal — only shows 5 built-in agents
Expected Behavior
Custom agents in .claude/agents/ should appear in the /agents dialog and claude agents output, as documented.
Actual Behavior
/agentsdialog: "No agents found. Create specialized subagents that Claude can delegate to."claude agentsoutput: Only lists 5 built-in agents (claude-code-guide, Explore, general-purpose, Plan, statusline-setup)
Additional Context
- 22 agent files exist in
.claude/agents/with valid frontmatter (name,descriptionfields present) - Files are UTF-8 encoded, no BOM
- File permissions are normal (
-rw-r--r--) - User-level agents at
~/.claude/agents/are also not discovered --agent <name>CLI flag is available but requires memorizing agent names
This issue has 8 comments on GitHub. Read the full discussion on GitHub ↗