[BUG] Agent Auto-Discovery Not Working - Agents Require --agents CLI Flag to Load

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Agents defined in .claude/agents/ directory with proper YAML frontmatter are not automatically discovered and registered in interactive Claude Code sessions. Instead, they require explicit loading via the --agents CLI flag. This creates an inconsistency with how slash commands work and requires workaround solutions.

Currently, agents defined in .claude/agents/:

1. Are discoverable by Claude's AI (Claude can read and understand the files)
2. But are not registered in the interactive session by default
3. Do not appear in /help or /agents output
4. Require users to manually pass --agents CLI flag with JSON configuration to load them
5. Require creating wrapper scripts/aliases as a workaround

What Should Happen?

Agents stored in .claude/agents/*.md with proper YAML frontmatter should be:

Automatically discovered on session start (similar to how .claude/commands/*.md are auto-discovered)
Automatically registered in the interactive session
Visible in /help and /agents commands without additional configuration
Available for use without requiring the --agents CLI flag

Error Messages/Logs

Steps to Reproduce

1. Create agent files in .claude/agents/ with proper YAML frontmatter:

yaml
---
name: my-agent
description: My custom agent
tools: Read, Grep, Glob, Bash
---

Agent instructions here...

1. Start Claude Code normally:

bashcd /path/to/project
claude

1. Try to use the agent:

/agents          # Agent doesn't appear
/help            # Agent not listed
@my-agent        # Agent not available

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

2.0.22

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

• Agents are defined with proper YAML frontmatter as per Claude Code format
• The feature works correctly when explicitly configured via --agents flag
• This is a usability/discoverability issue rather than a functional bug
• Community discussion suggests this is a gap in current implementation

Current Workaround
Have to create a wrapper script to explicitly pass agents via CLI:

bash
AGENTS_JSON=$(cat .claude/agents.json)
claude --agents "$AGENTS_JSON"

Or create an alias in shell config:

bash
alias name='cd /project && claude --agents