claude-code - 💡(How to fix) Fix [DOCS] [Subagents] Skill docs conflict on preload-only vs dynamic Skill tool access

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

• "Preload skills into subagents" section (lines 405–427)
• Skill behavior references in features-overview, skills, and context-window

Current Documentation

The subagent documentation describes skill preloading via the skills frontmatter field:

Use the skills field to inject skill content into a subagent's context at startup. This gives the subagent domain knowledge without requiring it to discover and load skills during execution.

And the same page says:

The full content of each skill is injected into the subagent's context, not just made available for invocation. Subagents don't inherit skills from the parent conversation; you must list them explicitly.

But other docs describe subagents more broadly:

The subagent has access to the same MCP servers and skills.

And:

Skills work differently in subagents. Instead of on-demand loading, skills passed to a subagent are fully preloaded into its context at launch. Subagents don't inherit skills from the main session; you must specify them explicitly.

The v2.1.133 changelog adds another signal about the intended behavior:

Fixed subagents not discovering project, user, or plugin skills via the Skill tool

What's Wrong or Missing?

A. The docs give conflicting guidance about what skills a subagent can access

sub-agents.md says subagents do not inherit skills from the parent conversation and must list them explicitly with the skills: frontmatter field. But context-window.md says a subagent has access to the same MCP servers and skills, and the v2.1.133 changelog confirms that subagents are expected to discover project, user, and plugin skills through the Skill tool.

The current docs do not explain whether "same skills" means:

• The same dynamic Skill tool catalog as the parent session
• Only skills preloaded through skills:
• Some combination of preloaded skills plus dynamically discoverable project/user/plugin skills

B. The distinction between preloaded skills and Skill tool discovery is not documented

The docs explain how to preload skills into a subagent, but they do not clearly separate that mechanism from runtime Skill tool discovery. Readers cannot tell when they should use skills: for guaranteed startup context versus relying on the Skill tool to discover project, user, and plugin skills during subagent execution.

Suggested Improvement

Clarify the subagent docs and cross-references so they distinguish preloading from runtime discovery. For example, add a subsection like:

#### Skills and the Skill tool in subagents

Subagents can preload skills with the `skills:` frontmatter field, which injects the full skill content into the subagent at startup.

This is different from runtime Skill tool discovery. During execution, subagents can discover the same project, user, and plugin skill catalog as the parent session, subject to the normal Skill tool and `disable-model-invocation` rules.

Use `skills:` when the subagent must start with specific skill content already in context. Use the Skill tool when the subagent should decide at runtime whether to load a project, user, or plugin skill.

Also update features-overview.md, skills.md, and context-window.md so they use the same terminology for subagent skill access.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Changelog reference: v2.1.133 — "Fixed subagents not discovering project, user, or plugin skills via the Skill tool"