claude-code - 💡(How to fix) Fix Docs: "/agents to load it immediately" wording is ambiguous — does not work for files added to disk directly [1 participants]

Where

https://code.claude.com/docs/en/sub-agents — the section on subagent loading reads:

Subagents are loaded at session start. If you create a subagent by manually adding a file, restart your session or use /agents to load it immediately.

What's ambiguous

The phrasing "use /agents to load it immediately" implies the slash command itself triggers a registry refresh from disk. In practice (tested 2026-05-03 in current Claude Code), opening /agents and dismissing the dialog does not pick up a new agent file written directly to ~/.claude/agents/ during the running session. The new agent does not appear in the dialog's listing, and subagent_type: <new-agent-name> calls fail.

A session restart picks the file up cleanly on next launch.

The likely interpretation is: /agents is an editor / management dialog for agents created or edited through the dialog itself — and changes made via the dialog do take effect immediately for the running session. But files added to disk by other means (Write tool, manual vim, cp, etc.) require a session restart.

Suggested clarification

One of:

1. If session restart is in fact required for off-dialog disk additions: rewrite the sentence to say so explicitly. Something like:

   Subagents are loaded at session start. To pick up a newly-added agent file written directly to disk, restart your session. The /agents slash command opens an interactive editor — agents you create or edit through the dialog take effect immediately, but it does not rescan the filesystem for files added by other means.

2. If there is an in-dialog action that triggers a rescan (e.g. a "Refresh" / "Rescan" item) that the empirical test missed: name it explicitly in the docs.

Why it matters

The current phrasing reads as if /agents is a generic reload mechanism. Anyone scripting agent creation (Write tool, codegen, sync from a shared config repo, etc.) hits this gap and concludes /agents is broken when in fact they're misreading the docs. A one-line tightening would prevent the iteration cost.

Reproducer

1. Start a Claude Code session.
2. Write a new file at ~/.claude/agents/foo.md with valid frontmatter (name: foo, description: ..., tools: ..., model: ...).
3. Run /agents and dismiss.
4. Try to spawn a subagent with subagent_type: foo — fails / not listed.
5. Restart the session, repeat step 4 — succeeds.

Tested with Claude Code current (Opus 4.7, 1M context), Darwin 25.4.0, zsh.