Custom agent in .claude/agents/ not loaded as subagent_type despite valid frontmatter
Resolved 💬 3 comments Opened May 9, 2026 by echelon-pocs Closed May 13, 2026
Description
One of 10 custom agents defined in .claude/agents/ (castor) is not available as a subagent_type in the Agent tool, even though:
- The file exists and has valid frontmatter (identical format to the other 9 agents in the same directory)
- All other 9 agents in
.claude/agents/are available assubagent_typevalues - The issue persists across new sessions — not a session-level caching problem
- The file is committed to git and clean (
git statusshows no changes)
Steps to reproduce
- Create 10 agent files in
.claude/agents/with identical frontmatter (name,description,tools,model: sonnet) - Commit all 10 files to git
- Start a Claude Code session in that project
- Attempt to invoke the missing agent via the
Agenttool withsubagent_type: "castor"
Error: Agent type 'castor' not found
- Start a new session — same result
castor.md frontmatter
---
name: castor
description: Infrastructure and networking specialist for the Jarbas project. Owns the physical and network substrate: UniFi configuration (VLANs, firewall, DNS, WireGuard), Docker/Podman host setup, NAS, the inference server OS, backups, and monitoring. Also owns the Gitea instance on Synology and the deploy agent on the inference server. Invoke Castor for any task involving hardware provisioning, network topology changes, container orchestration, system-level configuration, or operational runbooks.
tools: Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch
model: sonnet
---
Available agents returned by the Agent tool
argos, claude-code-guide, Explore, general-purpose, hermes, hestia, iris, janus, maestro, mercurius, Plan, pollux, statusline-setup, vesta
castor is absent. All other 9 custom agents from .claude/agents/ are present.
Key observations
castorsorts alphabetically betweenargos(works) andhermes(works) — not a truncation issue- All 10 agents were committed in the same git commit (
97c0c3a) - No difference in frontmatter structure between
castor.mdand working agents - Platform: Linux, cloud-based code-server environment
Expected behaviour
All agents in .claude/agents/ with valid frontmatter should be available as subagent_type values.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗