### 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. Th

[DOCS] [Subagents] Skill docs conflict on preload-only vs dynamic Skill tool access

Status Fixed / completed

Maintainer reply None cached

Activity 3 comments · opened May 8, 2026 · closed May 23, 2026

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:

| Page | Section | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | "Preload skills into subagents" | Says subagents must list skills explicitly, but does not explain runtime Skill tool discovery |
| https://code.claude.com/docs/en/features-overview | Skills vs Subagents | Says subagents can preload skills without clarifying the difference from dynamic discovery |
| https://code.claude.com/docs/en/context-window | Subagent context visualization | Says subagents have access to the same skills, which conflicts with the preload-only wording |
| https://code.claude.com/docs/en/skills | Skill tool behavior | Does not clarify how Skill tool discovery works inside subagents |

Total scope: 4 pages affected

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

View original on GitHub ↗

3 Comments

github-actions[bot] · 5 months ago

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

coygeek · 4 months ago

Issue #57154 Verification

Title: [DOCS] [Subagents] Skill docs conflict on preload-only vs dynamic Skill tool access
Issue Date: 2026-05-08
Verification Date: 2026-05-22
Status: RESOLVED

---

Issue Summary

This issue reports that the Claude Code docs were inconsistent about whether subagents can only use skills preloaded through the skills: field or can also discover project, user, and plugin skills dynamically through the Skill tool, and that the distinction between preloading and runtime discovery was not clearly documented.

---

Verification Results

Claim 1: The docs conflict about which skills subagents can access

Status: RESOLVED

At https://code.claude.com/docs/en/sub-agents, lines 411-425, the page now states: "Use the skills field to inject skill content into a subagent's context at startup" and "This field controls which skills are preloaded, not which skills the subagent can access: without it, the subagent can still discover and invoke project, user, and plugin skills through the Skill tool during execution."

At https://code.claude.com/docs/en/features-overview, line 256, the overview now states: "Skills work differently in subagents. Instead of on-demand loading, skills listed in the subagent's skills field are fully preloaded into its context at launch. Subagents can still discover and invoke unlisted project, user, and plugin skills through the Skill tool."

At https://code.claude.com/docs/en/context-window, line 262, the context-window page says: "The subagent has access to the same MCP servers and skills."

Verdict: The current documentation no longer presents preloading as the only way a subagent can access skills. The subagent and overview pages now explicitly distinguish preloaded startup context from runtime Skill tool discovery, so the current wording is consistent with the broader context-window description.

---

Claim 2: The distinction between preloaded skills and Skill tool discovery is not documented

Status: RESOLVED

At https://code.claude.com/docs/en/sub-agents, lines 425-427, the page now explicitly separates the two mechanisms: "This field controls which skills are preloaded, not which skills the subagent can access" and "To prevent a subagent from invoking skills entirely, omit Skill from the tools list or add it to disallowedTools."

At https://code.claude.com/docs/en/skills, line 214, the skills reference states that disable-model-invocation: true "prevents the skill from being preloaded into subagents."

At https://code.claude.com/docs/en/skills, lines 494-505, the skills page documents runtime Skill tool access: "By default, Claude can invoke any skill that doesn't have disable-model-invocation: true set" and "Disable all skills by denying the Skill tool in /permissions."

At https://code.claude.com/docs/en/changelog, line 432, the changelog records: "Fixed subagents not discovering project, user, or plugin skills via the Skill tool."

Verdict: The current docs now document the distinction between startup preloading and runtime Skill tool behavior. The subagent page explains the split directly, and the skills reference plus changelog align with that model.

---

Current State

| Claim | Status |
|-------|--------|
| The docs conflict about which skills subagents can access | RESOLVED |
| The distinction between preloaded skills and Skill tool discovery is not documented | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved.

---

References

URL: https://code.claude.com/docs/en/sub-agents
Lines 409-427: Preload section explains that skills: injects skill content at startup, does not limit total skill access, and still allows discovery of project, user, and plugin skills through the Skill tool.

URL: https://code.claude.com/docs/en/features-overview
Lines 256-256: Overview states that listed skills are preloaded at launch while unlisted project, user, and plugin skills remain discoverable through the Skill tool.

URL: https://code.claude.com/docs/en/context-window
Lines 262-262: Context-window description says the subagent has access to the same MCP servers and skills.

URL: https://code.claude.com/docs/en/skills
Lines 214-214: Frontmatter reference says disable-model-invocation: true prevents a skill from being preloaded into subagents.

URL: https://code.claude.com/docs/en/skills
Lines 494-505: Skill tool access rules explain default invocation behavior and how denying the Skill tool disables programmatic skill access.

URL: https://code.claude.com/docs/en/changelog
Lines 432-432: Changelog notes the fix for subagents discovering project, user, and plugin skills via the Skill tool.

---

Conclusion & Recommendation

Primary Concern: Whether the docs clearly distinguish subagent skill preloading from runtime Skill tool discovery.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current subagent documentation now states that the skills: field controls only preloaded startup context and does not define the full set of skills a subagent can access. The supporting overview, skills reference, context-window, and changelog text are consistent with that clarified behavior.

---

github-actions[bot] · 3 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.