## 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: ```markdown --- 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

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

Resolved 💬 22 comments Opened Jul 29, 2025 by dimension-zero Closed Jul 29, 2025

💡 Likely answer: A maintainer (ant-kurt, collaborator) responded on this thread — see the highlighted reply below.

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

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

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

Restart Claude Code
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.

View original on GitHub ↗

22 Comments

polishfreak · 11 months ago

review this there is a workaround

https://github.com/anthropics/claude-code/issues/4626

ebjllc621 · 11 months ago

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 collaborator · 11 months ago

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 · 11 months ago

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 · 11 months ago

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 · 11 months ago

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

stevenmenke · 11 months ago

Have the same issue on 1.0.67 (MacOS)

jasperf · 11 months ago

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 · 11 months ago

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.

paraddox · 11 months ago

I am using Claude on MacOS and this thing just happened to me after using them for the past couple of days with no problem.
Claude was not upgraded today. it is version 1.0.67
Weirdly it only sees the agent I have in the user folder, and one of the 7 agents I have in my project folder.

xgp0006 · 11 months ago

any luck with .69?

capslo · 11 months ago

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

ant-kurt collaborator · 11 months ago

For Windows native, this was resolved in 1.0.70.

macOS - please use one of the currently open issues like https://github.com/anthropics/claude-code/issues/5304

issogood · 11 months ago

the new version of claude code seems to need a header section in the subagent files:

example subagent file:

``gui-developer.md``

then the header needs to be

---
name: gui-develper
description: GUI developer
model: sonnet
color: blue
---

that worked for me

JustSuperHuman · 11 months ago

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.

This worked for me!

Used "Everything" app to search for "claude.exe" and "claude-code" and just deleted everything that showed up. @ symbol worked to find files after I reinstalled it.

zfogg · 11 months ago

it's still broken for me... :( someone @ me when it's fixed 👍🏾😮‍💨

JustSuperHuman · 11 months ago

@zfogg removing completely and reinstalling fixed it!

I did the scorched earth method above and just deleted every reference to claude.exe / claude-code on my computer. Then ran npm install -g @anthropic-ai/claude-code

not directly related but this tool is a hidden gem and will search for everything instantly
(sounds like selling something but honestly just like sharing that it's cool)
https://www.voidtools.com/support/everything/

can also install from Ninite (another cool tool if you never used)

going to bed <3

thibaud57 · 11 months ago

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.

It was the solution thanks man !

capslo · 11 months ago

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.

Works thanks

nadeem4 · 11 months ago

In my case, I created one .md.backup file, which was causing the issue. Also, I had one md file that was not following the Anthropic sub-agents structure.

vmadman · 11 months ago

In trying to avoid spamming every thread with the same, long, description, I've posted how I fixed this issue here: https://github.com/anthropics/claude-code/issues/4623#issuecomment-3187221181

github-actions[bot] · 10 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.