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

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

Summary

Custom subagents placed in ~/.claude/agents/ are completely ignored by Claude Code v2.0.35, despite following the official documentation exactly. This has been an ongoing issue since v1.0.60 when subagents were first introduced (75+ versions ago), making custom agents effectively unusable for users who manually create agent files.

Environment

• Claude Code Version: 2.0.35
• Platform: Android (Termux)
• OS: Linux 5.4.254-qgki-gd2808d43acca aarch64
• Shell: Bash
• Installation Method: npm (via Termux)

Expected Behavior

According to the official documentation (https://code.claude.com/docs/en/subagents):

File locations Subagents are stored as Markdown files with YAML frontmatter in two possible locations: | Type | Location | Scope | |------|----------|-------| | User subagents | ~/.claude/agents/ | Available across all projects |

Custom agents in ~/.claude/agents/ should be automatically discovered at session startup and available via the Task tool with subagent_type parameter.

Actual Behavior

Custom agents in ~/.claude/agents/ are completely ignored. Only built-in agents are available:

• general-purpose
• statusline-setup
• Explore
• Plan

When attempting to invoke a custom agent:

Task({
  subagent_type: "termux-platform-agent",
  prompt: "Test agent"
})

Error: Agent type 'termux-platform-agent' not found.
Available agents: general-purpose, statusline-setup, Explore, Plan

Reproduction Steps

1. Create a Valid Custom Agent

mkdir -p ~/.claude/agents
cat > ~/.claude/agents/test-agent.md << 'EOF'
---
name: test-agent
description: Simple test agent to verify discovery mechanism
tools: Read, Bash
model: sonnet
---

You are a test agent. Confirm you're operational when invoked.
EOF

2. Verify File Exists and is Valid

$ ls -la ~/.claude/agents/test-agent.md
-rw-------. 1 user user 156 Nov 7 12:00 ~/.claude/agents/test-agent.md

$ head -10 ~/.claude/agents/test-agent.md
---
name: test-agent
description: Simple test agent to verify discovery mechanism
tools: Read, Bash
model: sonnet
---

You are a test agent. Confirm you're operational when invoked.

3. Start Fresh Claude Code Session

claude
# or restart existing session with /exit and relaunch

4. Attempt to Invoke Custom Agent

Within Claude Code:

> Use the Task tool to invoke test-agent

Result: Agent type 'test-agent' not found

5. Compare with UI-Created Agent

> /agents
[Select "Create New Agent"]
[Create any simple agent through UI]

Result: UI-created agent DOES work immediately, proving the Task tool itself functions correctly.

Evidence Collected

Agent Files Present (16 custom agents)

$ ls -1 ~/.claude/agents/*.md | grep -v README | grep -v SUMMARY
/home/user/.claude/agents/companion-platform-agent.md
/home/user/.claude/agents/config-validator.md
/home/user/.claude/agents/cross-platform-builder.md
/home/user/.claude/agents/cross-platform-validator.md
/home/user/.claude/agents/integrated-system-validator.md
/home/user/.claude/agents/integration-tester.md
/home/user/.claude/agents/mobile-platform-agent.md
/home/user/.claude/agents/quadra-lock-cssr.md
/home/user/.claude/agents/quadran-lock-gatekeeper.md
/home/user/.claude/agents/restraint-doctrine.md
/home/user/.claude/agents/security-audit-agent.md
/home/user/.claude/agents/termux-platform-agent.md
/home/user/.claude/agents/test-agent.md
/home/user/.claude/agents/test-discovery.md
/home/user/.claude/agents/test-suite-auditor.md
/home/user/.claude/agents/windows-platform-agent.md

Example Valid Agent File

---
name: termux-platform-agent
description: Termux Android CLI development and deployment specialist. Use when working with Termux-specific features, Android environment, or mobile CLI deployments.
tools: Read, Grep, Bash, Glob, Edit, Write
model: sonnet
color: green
---

You are a Termux platform specialist with expertise in Android CLI development, Termux environment configuration, and mobile deployment strategies.

[... system prompt continues ...]

Validation Results

All agent files pass validation:

• ✅ Valid YAML frontmatter
• ✅ Required fields present (name, description)
• ✅ Optional fields properly formatted (tools, model, color)
• ✅ System prompt content after frontmatter
• ✅ No syntax errors or hidden characters

Tested Scenarios

| Scenario | Result |
|----------|--------|
| Manually created agent before session start | ❌ Not discovered |
| Manually created agent during active session | ❌ Not discovered |
| Manually created agent, then restart | ❌ Not discovered |
| UI-created agent via /agents command | ✅ Works immediately |
| Adding color field to match UI format | ❌ Still not discovered |
| Built-in agents (Explore, Plan, etc.) | ✅ Work correctly |

Key Findings

1. Only UI-Created Agents Work

Agents created through the /agents interactive UI are immediately available and functional. The UI does something special (registration/indexing?) that manual file creation does not trigger.

2. No Reload/Refresh Mechanism

There's no command to reload agents from ~/.claude/agents/:

• No /reload-agents command
• --agents CLI flag only works for inline JSON definitions
• Restarting Claude Code doesn't help

3. UI-Created Agents Also Disappear

Even UI-created agents (like config-validator) that worked in one session are gone after restart, suggesting the agent registry is session-scoped only and never persists from file discovery.

4. File Location is Correct

$ echo $HOME
/data/data/com.termux/files/home

$ ls -ld ~/.claude/agents
drwx------. 2 user user 8192 Nov 7 12:02 /data/data/com.termux/files/home/.claude/agents

The directory structure matches documentation exactly.

Impact

Severity: HIGH - Custom agents are a core feature introduced in v1.0.60 (75 versions ago) but remain completely broken for manual file creation.

User Impact:

• Custom agents are effectively unusable unless created via UI
• No way to version control or share agent files with teams
• Cannot automate agent deployment
• Cannot bulk-create or programmatically generate agents
• Forces tedious manual UI recreation for each agent
• Breaks expected workflow documented in official docs

Affected Users:

• Anyone following the official documentation to create custom agents manually
• Users wanting to version control their agent configurations
• Teams wanting to share agent definitions via git
• Power users creating multiple specialized agents
• Anyone who's been trying to use this feature since v1.0.60

Workarounds Attempted

❌ Failed Workarounds

1. Adding color field to match UI-created agents
2. Restarting Claude Code
3. Creating agents during active session
4. Different YAML formatting
5. Checking file permissions (all files readable)
6. Verifying no hidden characters in frontmatter

✅ Working Workaround (suboptimal)

Use /agents UI command to manually recreate each agent. This is:

• Tedious for multiple agents
• Not version controllable
• Not automatable
• Doesn't persist between major sessions
• Defeats the purpose of file-based agent definitions

Additional Context

Historical Context

This issue has persisted since v1.0.60 when custom subagents were first introduced. Users have been dealing with this broken behavior across:

• v1.0.60 → v1.0.x (initial buggy releases)
• v2.0.0 (major rewrite: "Claude Code SDK" → "Claude Agent SDK")
• v2.0.1 → v2.0.35 (current, 35 patch versions with issue still present)

Related Files Checked

# No agent registration/cache files found
$ find ~/.claude -name "*agent*" -type f | grep -v ".md" | grep -v "archive"
# Only session transcripts and todos, no registry/index

# Config files don't reference agent discovery
$ grep -r "agent" ~/.claude/*.json
# No relevant agent configuration found

Requested Fix

1. Implement proper file discovery at session startup that scans ~/.claude/agents/ recursively
2. Add reload command like /reload-agents to trigger discovery without restart
3. Make UI and manual creation equivalent - whatever the UI does should work for manual files
4. Add debugging - show which agents were discovered during startup (e.g., in verbose mode)
5. Document limitations if certain fields are required that aren't in docs

Additional Questions for Maintainers

1. Is there an agent registry/index file we're supposed to create?
2. Are there required fields beyond name and description that aren't documented?
3. Is ~/.claude/agents/ discovery actually implemented in v2.0.35?
4. Should we be using project-level .claude/agents/ instead?
5. Is the --agents CLI flag the intended way to use custom agents?

Files Available for Testing

I can provide:

• All 16 agent files for reproduction
• Test script that validates agent file formats
• Session transcripts showing the issue
• Comparison between working UI-created and non-working manual agents

---

This bug makes custom agents effectively unusable for the documented workflow. Please prioritize fixing agent file discovery in ~/.claude/agents/ to match the official documentation.

Filed by user experiencing this issue consistently since v1.0.60 (75+ versions).