Custom subagent not recognized by Agent tool despite valid definition file (works for sibling agents in same directory)

Status Open
Maintainer reply None cached
Activity 0 comments · opened Aug 29, 2026

Description

I have 4 custom subagent definition files in .claude/agents/, all with the same frontmatter structure (name, description, tools, model). 3 of them are correctly recognized and callable via the Agent tool. The 4th is not — the Agent tool errors with Agent type '<name>' not found, and the error's "Available agents" list does not include it.

Steps to reproduce

  1. Have multiple custom subagents defined in .claude/agents/*.md in a project.
  2. Confirm most are listed as available agent types and callable.
  3. One specific agent, despite an identically-structured definition file, is missing from the available agent list and fails to invoke.
  4. To rule out a file-content issue: delete the problematic agent's .md file entirely and rewrite it from scratch (new content, same frontmatter shape as the working sibling agents) within the same session.
  5. Retry invoking it — still fails with the same error, and it's still absent from the "Available agents" list.

Expected behavior

Either the agent should be recognized (matching its working siblings), or if there's a registry rescan requirement, deleting and recreating the file within the same session should trigger it.

Actual behavior

The agent remains permanently absent from the available agent list for the entire session, even after a full delete + from-scratch recreation of its definition file. This suggests the agent registry may only be scanned once at session start and never rescanned, or there's a bug in the registry scan logic itself (possibly related to file ordering, count, or some other environmental factor rather than file content, since content was ruled out).

Environment

  • OS: Windows 11 Pro
  • Shell: PowerShell (primary)
  • All 4 subagent definition files use non-ASCII (Korean) filenames and name fields — this doesn't appear to be the root cause since 3 of the 4 Korean-named agents work fine, but noting it in case it's relevant to directory scanning.

Additional notes

Happy to provide the (sanitized) contents of the working vs. non-working agent definition files if useful for reproduction.

View original on GitHub ↗