[DOCS] Subagent docs omit the colon restriction for local agent names

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

Subagent frontmatter naming and the relationship between local agent names and plugin-scoped names.

Current Documentation

The page currently says:

The subdirectory path doesn't affect how a subagent is identified or invoked, because identity comes only from the name frontmatter field.

It also documents plugin-scoped identifiers such as my-plugin:db-agent, but does not state that a colon is reserved and rejected in an agent markdown file’s own name value.

What's Wrong or Missing?

Claude Code 2.1.218 changed agent markdown validation so names containing : are rejected because the character is reserved for plugin namespacing.

The current documentation shows colon-containing identifiers in examples for plugins while leaving the local-agent naming rule implicit. Authors can therefore put a namespaced-looking value in a local agent’s frontmatter and receive a validation failure without knowing that the colon is reserved for the plugin scope.

Suggested Improvement

Add a naming rule to the subagent frontmatter documentation:

Local and user/project agent name values must not contain :. A colon is reserved for plugin-scoped identifiers such as my-plugin:reviewer; use a plain name for a local agent and let the plugin supply the namespace for plugin agents.

Show one valid local name and one valid plugin-scoped name, and document the validation error or /doctor guidance when a local agent contains a colon.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/sub-agents | Agent frontmatter name and invocation |
| https://code.claude.com/docs/en/plugins | Plugin namespaces and scoped agent identifiers |
| https://code.claude.com/docs/en/plugins-reference | Plugin component naming and validation |

Total scope: 3 pages should distinguish local names from plugin-scoped names.

The behavior was changed in Claude Code v2.1.218.