claude-code - 💡(How to fix) Fix Claude provides incorrect guidance about its own /agents feature, causing ~2M token waste

Environment

• Claude Code Desktop v2.1.156
• Windows (entrypoint: claude-desktop)
• Max plan subscriber
• Session ID: 71b8d81b-1505-46d8-afe3-d84b74baad64
• Date: 2026-05-29

Description

When asked about migrating custom agent definitions to the Claude Code subagent system, Claude confidently stated that placing .md files with YAML frontmatter in ~/.claude/agents/ would make them appear in the /agents Library tab. It then:

1. Created ~/.claude/agents/ and copied 22 agent .md files there (~170K tokens)
2. When only 2 appeared, assumed file size was the cause (no verification)
3. Launched a 22-agent parallel workflow to condense all files (~1M tokens)
4. 4 agents failed, retried them in background and foreground (~450K tokens)
5. After all files were condensed and verified, agents still did not appear
6. Research into the actual discovery mechanism was inconclusive

Total wasted tokens: ~1.7-2M across the session.

Root Cause

Claude does not accurately know how its own /agents feature discovers and loads custom agent definitions in the desktop app. Rather than acknowledging uncertainty and testing with a single file first, it proceeded confidently through multiple expensive operations.

Expected Behavior

1. Claude should accurately describe its own product features, or explicitly state uncertainty
2. Expensive operations (multi-agent workflows) should not be launched based on unverified assumptions about product behavior
3. Max plan users should have a mechanism to flag sessions like this for token credit consideration

Reproduction

1. Open Claude Code Desktop
2. Ask Claude to help migrate agent definitions to /agents
3. Observe that Claude will confidently describe a file-based mechanism and execute on it without verifying it works

Impact

~2M tokens of Max plan allocation consumed with zero functional result. Anthropic has full telemetry for session 71b8d81b-1505-46d8-afe3-d84b74baad64 to verify.