[BUG] Custom Subagents in ~/.claude/agents/ Not Discovered or Loaded (v2.0.35)

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/8256
2. https://github.com/anthropics/claude-code/issues/5289
3. https://github.com/anthropics/claude-code/issues/9366

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

This is a issue, seriously

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

i never had this problem until "upgrading" to 2.1.1 this week.
now 2 of my 5 custom agents are not showing up. they had previously worked well for several months.

after letting claude flail around trying to figure it out across several sessions, the best it could come up with
is that it may be related to the size of the agent definition file (the files defining the missing agents are 17548
and 29387 bytes; of the ones that show up, the largest size is 15541). however, it seems pretty unlikely that
size would be the issue. claude's own analysis showed no syntax or related issues with the definitions of the
missing agents, which have been stable for several weeks. the only change has been CC itself.

CC 2.1.1 on macos

notable output from /doctor:

 Agent Parse Errors
 └ Failed to parse 2 agent file(s):
   └ /Users/jpf/.claude/agents/tech-translator-en-ja.md: Missing required "name" field in frontmatter
   └ /Users/jpf/.claude/agents/android-build-expert.md: Missing required "name" field in frontmatter

however, both files do have properly defined name fields.

update 2 - a possible solution (for the issue as described in this comment anyway):
upon closer inspection of the failing-to-parse definition files, i became suspicious of the way the description
fields were formatted, specifically with regard to quoting. all my agents have been developed via an iterative
process wherein i ask claude to create an agent definition based on my criteria, which are then refined over
the course of different sessions as issues are discovered or enhancements are required. this is done not by
using the /agents interface, but rather by discussing the changes with CC and then having it edit the files
directly. across various refinement sessions, some of the descriptions became quite complex (spanning multiple
lines, containing both single and double-quotes, colons, XML-like markup, etc.). my issue turns out to have been
caused by these (formerly parse-able) descriptions. apparently 2.1.x is using stricter parsing for the YAML
frontmatter. when i updated the description fields to use literal block scalars, the issue no longer occurred.
hopefully this may help others if they've been experiencing similar problems since 2.1 ...

properly quoted description block, e.g.:

---
name: android-build-expert
description: |
  Use this agent when you need expertise with Android app builds, Gradle build system, Android Gradle Plugin (AGP), dependency management, build configuration, or Flutter Android builds. This includes tasks like analyzing Gradle configurations, understanding build file impacts, optimizing build performance, debugging build failures, ensuring build reproducibility, or understanding how Android build components interact. Examples:

  <example>
  Context: The user needs to understand which Gradle files affect build output.
  user: "What Gradle configuration files can affect my Android build output?"
  assistant: "I'll use the android-build-expert agent to explain which Gradle files affect build output and how each impacts your builds."
  <commentary>
  Understanding configuration file impacts requires deep knowledge of Gradle build lifecycle and plugin architecture - perfect for the android-build-expert agent.
  </commentary>
  </example>
[...]
model: opus
color: yellow
---

Same issue here.

The problem in my case was the examples containing html blocks. Regardless, i used claude to fix claude :)

I just used the /doctor output as input for this query:

❯ My agent files have issues. They have a name property but the examples are probably messing something up?
 <doctor output>
  Inspect and fix them!

That fixed them all.
Claude probably needs to be a little less strict in it's parsing or use itself to parse those files and install those agents.

Confirmed Bug in Claude Code 2.1.7

Everything is set up correctly:

• ✅ .claude/agents/ directory exists
• ✅ 9 agent files with proper YAML frontmatter
• ✅ Files are readable
• ✅ Format matches documentation

But /agents shows "No agents found" - this is a regression bug.

You should report this:

Issue: Custom agents in .claude/agents/ not loaded

Claude Code version: 2.1.7
OS: macOS Darwin 25.2.0

Steps to reproduce:

1. Create .claude/agents/code-reviewer.md with valid YAML frontmatter
2. Run /agents command
3. Shows "No agents found" despite files existing

Expected: Agents from .claude/agents/*.md should appear in /agents list
Actual: "No agents found"

Agent file format (confirmed valid per docs):
---
name: code-reviewer
description: Use this agent to perform comprehensive code reviews...
model: opus
---
[agent body]

Samesies, running 2.1.31 on Windows and we have several agents defined in .claude/agents which worked before but which no longer load. Very annoying. I tried using /feedback to report the bug in Claude, but it kept cancelling out after typing a few characters in the bug description (which may itself be a bug...)

Yet persists

Claude CLI created subagents loaded uncompletely. Only one out of several PERSONAL agents from ~/.claude/agents and one out of several PROJECT agents from .claude/agents.

verified on version: 2.1.80 and 2.1.62

This was plaguing me and seemed random.
Took a copy of the leaked source code and made a utility with better error reporting in between steps to look up agents by file.

For our use case, we were installing globally in a devcontainer via npm and the following resolved the issue for us.

Root cause: npm install -g @anthropic-ai/claude-code strips execute permissions from the vendor ripgrep binary (vendor/ripgrep/x64-linux/rg gets 644 instead of 755). CC's loadMarkdownFiles() catches the resulting EACCES error and silently returns [].

fix:

chmod +x $(npm root -g)/@anthropic-ai/claude-code/vendor/ripgrep/*/rg

The relevant caller from cc => loadMarkdownFiles() in claude-code/src/utils/markdownConfigLoader.ts, lines 546-600:

/**
 * Generic function to load markdown files from specified directories
 * @param dir Directory (eg. "~/.claude/commands")
 * @returns Array of parsed markdown files with metadata
 */
async function loadMarkdownFiles(dir: string): Promise<
  {
    filePath: string
    frontmatter: FrontmatterData
    content: string
  }[]
> {
  // File search strategy:
  // - Default: ripgrep (faster, battle-tested)
  // - Fallback: native Node.js (when CLAUDE_CODE_USE_NATIVE_FILE_SEARCH is set)
  //
  // Why both? Ripgrep has poor startup performance in native builds.
  const useNative = isEnvTruthy(process.env.CLAUDE_CODE_USE_NATIVE_FILE_SEARCH)
  const signal = AbortSignal.timeout(3000)
  let files: string[]
  try {
    files = useNative
      ? await findMarkdownFilesNative(dir, signal)
      : await ripGrep(
          ['--files', '--hidden', '--follow', '--no-ignore', '--glob', '*.md'],
          dir,
          signal,
        )
  } catch (e: unknown) {
    // Handle missing/inaccessible dir directly instead of pre-checking
    // existence (TOCTOU). findMarkdownFilesNative already catches internally;
    // ripGrep rejects on inaccessible target paths.
    if (isFsInaccessible(e)) return []
    throw e
  }

  const results = await Promise.all(
    files.map(async filePath => {
      try {
        const rawContent = await readFile(filePath, { encoding: 'utf-8' })
        const { frontmatter, content } = parseFrontmatter(rawContent, filePath)

        return {
          filePath,
          frontmatter,
          content,
        }
      } catch (error) {
        const errorMessage =
          error instanceof Error ? error.message : String(error)
        logForDebugging(
          `Failed to read/parse markdown file:  ${filePath}: ${errorMessage}`,
        )
        return null
      }
    }),
  )

  return results.filter(_ => _ !== null)
}

Reproducing on macOS Darwin 25.2.0 with Claude Code v2.1.143

Hit this today — confirming the bug is platform-agnostic and still present 75+ versions later.

Environment

• Claude Code: v2.1.143
• OS: macOS Darwin 25.2.0
• Install: official CLI

Setup

• 3 user-level custom agents at ~/.claude/agents/:
• fetch-vault.md (tools: Read, Glob, Grep)
• vault-curator.md (tools: Read, Edit, Glob, Grep, Bash)
• vault-scribe.md (tools: Read, Write, Edit, Glob, Grep)
• All have valid frontmatter (name, description, tools, model: inherit)
• No project-level .claude/agents/ involved
• ~/.claude/settings.json and ~/.claude/settings.local.json contain no agent-related allow/deny rules

Observed

• ✅ Agents ARE discovered at startup — they appear in the Agent tool's static description in the system prompt, with their descriptions intact
• ❌ Agents are NOT in the runtime registry — calling \Agent(subagent_type="fetch-vault", ...)\ returns:

> \Agent type 'fetch-vault' not found. Available agents: claude-code-guide, Explore, general-purpose, Plan, statusline-setup\

• Only the 5 built-in subagents are invocable. Custom names hit the dead branch.

Downstream effect
Any slash-command or skill that wraps a custom subagent fails mid-flow. In my case /fetch_agent (a thin wrapper around Agent(subagent_type="fetch-vault", ...)) errors out at every invocation.

Discovery vs runtime registry are out of sync. Discovery scans ~/.claude/agents/ correctly; the registry that gates the Agent tool's subagent_type enum doesn't see them.

Likely same root cause as the open #59881 (project-scope) and the closed-as-dup #20931.

Still hitting this on Linux (x86_64, npm install, v2.0.35+) — not Termux-specific. Reproduces the same way: agents in ~/.claude/agents/ are silently ignored, only the four builtin types (general-purpose, Plan, Explore, statusline-setup) resolve, and subagent_type: "<custom>" returns Agent type 'X' not found.

A few diagnostic notes from chasing this down on my end — sharing in case they help narrow it:

1. Project-scoped agents under <project>/.claude/agents/ work fine. The discovery bug is specific to the user-scoped path. That tells me the file format, YAML frontmatter, and CLI-side parsing are all healthy — what's broken is whichever code path walks ~/.claude/agents/ at session init.

1. claude --list-agents (when available in your build) confirms it. On affected builds, the user-scoped directory contents simply don't appear in the listing. That decouples the bug from "discovery happened but resolution failed" — it's a load-time miss, not a runtime mismatch.

1. Symlinking project-scoped onto user-scoped works as a workaround. ln -s ~/.claude/agents/my-agent.md <project>/.claude/agents/my-agent.md is ugly but it side-steps the missing user-scope walker entirely. Useful only if you've got a small number of projects.

1. The "75+ versions and still broken" framing is the load-bearing point. This isn't a fresh regression — it's a feature gap masquerading as a bug. Anyone building a personal agent library (the documented use case for the user-scoped path) is effectively unable to use it, which is why the same issue keeps getting reopened under slightly different titles (#41973, #58353 etc.).

If a maintainer wants more debug surface, happy to share strace/fs_usage traces showing the session-init process never opens any path under ~/.claude/agents/ on affected builds — the absence of those file opens is the clearest fingerprint of the load-time miss.