[BUG] Custom agents in project-local .claude/agents/ directory not discovered by /agents command

Resolved 💬 8 comments Opened Jul 30, 2025 by geverit4 Closed Aug 7, 2025

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:

  1. User agents (global): ~/.claude/agents/ - available across all projects
  2. 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

  1. Create a .claude/agents/ directory in your project root
  2. Create a custom agent definition file (e.g., npm-atomic-publisher.md) in .claude/agents/
  3. Restart Claude Code
  4. 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

View original on GitHub ↗

This issue has 8 comments on GitHub. Read the full discussion on GitHub ↗