[BUG] Custom agents in project-local .claude/agents/ directory not discovered by /agents command
Environment
- Platform (select one):
- Anthropic API
- Claude CLI version: Claude Code Status v1.0.63
- Operating System: macOS (Darwin 24.5.0)
- Terminal:
Bug Description
The /agents command does not discover custom agents placed in the project-local .claude/agents/ directory. According
to the Claude Code documentation, custom agents can be placed in both locations:
- User agents (global): ~/.claude/agents/ - available across all projects
- Project agents (local): .claude/agents/ - specific to your project
The documentation specifically states that project agents in .claude/agents/ are "specific to your project" and
designed to be shared with your team, indicating they should be discoverable by Claude Code.
Steps to Reproduce
- Create a .claude/agents/ directory in your project root
- Create a custom agent definition file (e.g., npm-atomic-publisher.md) in .claude/agents/
- Restart Claude Code
- Run the /agents command
Expected Behavior
The /agents command should list both global agents from ~/.claude/agents/ and project-local agents from
.claude/agents/, showing the custom npm-atomic-publisher agent.
Actual Behavior
The /agents command only shows built-in agents and does not discover the custom agent placed in the project-local
.claude/agents/ directory, even after restarting Claude Code.
Additional Context
- The agent file is properly formatted with valid Markdown content
- File permissions appear correct (readable)
- Global agents in ~/.claude/agents/ work as expected
- The issue persists after Claude Code restart
This issue has 8 comments on GitHub. Read the full discussion on GitHub ↗