Custom agents in ~/.claude/agents/ not detected by /agents command

[dimension-zero]

Issue Description

Custom agents placed in ~/.claude/agents/ are not being detected or listed by the /agents command, despite following the documented format.

Steps to Reproduce

1. Create ~/.claude/agents/someagent.md with proper YAML frontmatter:

---
name: someagent
description: Use this agent when you need
[... rest of agent content ...]

2. Restart Claude Code
3. Run /agents command

Expected Behavior

The someagent agent should appear in the agents list and be available for use.

Actual Behavior

• /agents shows "No agents found"
• Only general-purpose appears as built-in
• Custom agent is not detected or usable

Environment

• Platform: Windows 11
• Claude Code: Latest version
• File location: C:\Users\[username]\.claude\agents\someagent.md
• File encoding: ASCII text
• File format: Validated against documentation

Additional Information

• File exists and is readable
• YAML frontmatter follows documented format exactly
• Tried recreating the file multiple times
• Created minimal test agent with same result
• Documentation suggests this should work: https://docs.anthropic.com/en/docs/claude-code/sub-agents

File Contents

The agent file follows the exact format specified in the documentation:

• Valid YAML frontmatter with name and description fields
• Proper markdown content below the frontmatter
• No extraneous fields or formatting issues

This appears to be a bug in the agent detection/loading system rather than a user configuration issue.

[polishfreak]

review this there is a workaround

#4626

[ebjllc621]

I had been using the workaround to downgrade to version 1.0.61 all day with success until about 30 min ago. CC locked up in the terminal. Fired up a new session and downgraded my version only to no longer be able to use my commands or custom agents in 1.0.61

[ant-kurt]

Issues with custom agents, file search, and custom slash commands on Windows should be resolved for CMD and Powershell in 1.0.63, which released today but is not yet tagged as latest.

Downgrading to 1.0.61 will also mitigate.

[nsxdavid]

Just to be clear, @ant-kurt, these issues still persist in 1.0.63 (Windows Native).

• /agents does not see any agents (other than general-purpose) despite both project and personal agents existing.
• @ only shows agents, not files anymore (and in this case only the general-purpose agent).
• Custom / commands do not show either.

Verified version:
1.0.63 (Claude Code)

[commandodev]

I'm still seeing this with 1.0.65 installed through nix and though npm. I don't see any custom agents or commands and I don't see anything in the logs when started with -d

[B0PE]

Issues still persist for me in 1.0.67 (Windows Native).

[stevenmenke]

Have the same issue on 1.0.67 (MacOS)

[jasperf]

For me /agents does not work. Added a sub agent manually to .claude/agents/design-analyzer.md in project , restarted Claude Code in VS Code. But still it is not detected . Updated to latest Claude Code

Claude Code Status v1.0.55

  L Session ID: xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx

 Working Directory 
  L /Users/me/code/project

 IDE Integration • /config
 ✔  Connected to Visual Studio Code extension
  L Installed VS Code extension version 1.0.55 (server version: 1.0.67)

 Account • /login
  L Login Method: Claude Pro Account
  L Organization: me@domain.com's Organization
  L Email: me@domain.com

 Model • /model
  L Sonnet Sonnet 4 for daily use

[dimension-zero]

TOP TIP: check for MULTIPLE installations of Claude Code. I ended up with three on same machine, each in different location. I uninstalled them all and then did a fresh install from npm install -g @anthropic-ai/claude-code. Agents now being recognized.