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 as subagent_type values
  • The issue persists across new sessions — not a session-level caching problem
  • The file is committed to git and clean (git status shows no changes)

Steps to reproduce

  1. Create 10 agent files in .claude/agents/ with identical frontmatter (name, description, tools, model: sonnet)
  2. Commit all 10 files to git
  3. Start a Claude Code session in that project
  4. Attempt to invoke the missing agent via the Agent tool with subagent_type: "castor"

Error: Agent type 'castor' not found

  1. 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

  • castor sorts alphabetically between argos (works) and hermes (works) — not a truncation issue
  • All 10 agents were committed in the same git commit (97c0c3a)
  • No difference in frontmatter structure between castor.md and 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.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗