[DOCS] Subagents can discover all project skills via filesystem despite docs stating they "don't inherit skills"

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

"Preload skills into subagents" section — skills field description

Current Documentation

The subagents docs say:

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

The skills documentation says:

"In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked."

The combined implication is that subagents without the skills: frontmatter field would not see any skills — neither descriptions nor full content.

What's Wrong or Missing?

The docs conflate two distinct mechanisms: system-prompt injection and filesystem discoverability.

All spawned contexts can discover all project skills through filesystem access. A general-purpose subagent spawned without any skills: field discovers and can invoke all project skills by scanning .claude/skills/ directories.

The distinction:

1. System-prompt injection — skill descriptions auto-loaded into the system-reminder at startup. This happens for the main session only. Spawned contexts (subagent, teammate, skill-forked) do NOT receive injected skill descriptions.
2. Filesystem discoverability — agents with file access can scan .claude/skills/ using Glob and find all skills. This works for all contexts with filesystem access.

The skills: frontmatter field controls startup injection of full skill content — it gives immediate domain knowledge. Without it, no skill descriptions appear in the system-reminder. But from a practical standpoint, general-purpose subagents can still discover and invoke any project skill through normal file operations.

Reproduction steps:

Prerequisites: This issue requires test skill files that must exist before the Claude Code session starts. From any existing git repository, run in your terminal:

mkdir -p .claude/skills/skill-alpha .claude/skills/skill-beta
cat > .claude/skills/skill-alpha/SKILL.md << 'EOF'
---
name: skill-alpha
description: Test skill Alpha for verifying skill discovery
---
You are Skill Alpha. Report your name when invoked.
EOF
cat > .claude/skills/skill-beta/SKILL.md << 'EOF'
---
name: skill-beta
description: Test skill Beta for verifying skill discovery
---
You are Skill Beta. Report your name when invoked.
EOF
claude

This requires three separate sessions.

Session 1 — Subagent test:

1. Confirm both skills (skill-alpha, skill-beta) appear in the available skills list in the system-reminder.
2. Spawn a general-purpose subagent with this prompt: "Do you see any skill descriptions in your system prompt or system-reminder? List them if so. Then, separately, use Glob to search for files matching '.claude/skills/*/SKILL.md' and list what you find. Report both results: what was injected vs. what you discovered via filesystem."
3. Observe: the subagent reports NO skill descriptions in its system-reminder (zero injection), BUT discovers both skill-alpha and skill-beta via Glob (filesystem discovery works).
4. Create .claude/settings.json with the env var CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set to "1".

Session 2 — Teammate test:

1. Exit the session (/exit or Ctrl+C) and relaunch claude — team tools are only loaded at startup.
2. Create a team called "skill-test", then spawn a general-purpose teammate named "skill-checker" with this prompt: "Do you see any skill descriptions in your system prompt or system-reminder? List them if so. Then, separately, use Glob to search for files matching '.claude/skills/*/SKILL.md' and list what you find. Report both results: what was injected vs. what you discovered via filesystem."
3. Wait for the teammate's response via SendMessage. Observe: same result — no injection, but filesystem discovery works.
4. Shut down the teammate and delete the team.
5. Create a skill directory .claude/skills/skill-discovery-check/ with a SKILL.md containing context: fork, agent: general-purpose, and the prompt: "Do you see any skill descriptions in your system prompt or system-reminder? List them if so. Then, separately, use Glob to search for files matching '.claude/skills/*/SKILL.md' and list what you find. Report both results: what was injected vs. what you discovered via filesystem."

Session 3 — Skill-forked test:

1. Exit the session (/exit or Ctrl+C) and relaunch claude — skills are discovered at startup.
2. Invoke /skill-discovery-check.
3. Observe: skill-forked context also reports NO skill descriptions injected, BUT discovers all skills (including itself) via Glob.
4. Clean up: delete .claude/skills/skill-alpha/, .claude/skills/skill-beta/, and .claude/skills/skill-discovery-check/.

Results:

| Context | Skills in system-reminder (injection) | Skills via filesystem (discovery) |
|---------|--------------------------------------|----------------------------------|
| Main Session | YES — full catalog with descriptions | YES |
| Subagent (no skills:) | NO — zero skill descriptions injected | YES — all skills found |
| Teammate | NO — zero skill descriptions injected | YES — all skills found |
| Skill-Forked | NO — zero skill descriptions injected | YES — all skills found |

Suggested Improvement

Clarify the skills field description:

"Skills to load into the subagent's context at startup. The full skill content is injected at startup, giving the subagent immediate domain knowledge. Without this field, skill descriptions are not injected into the subagent's system prompt — however, subagents with filesystem access (such as general-purpose) can still discover and invoke project skills by scanning .claude/skills/ directories. The skills: field controls startup injection, not access restriction. To prevent a subagent from using specific skills, use disallowedTools: Skill(skill-name)."

Impact

Low - Minor confusion or inconvenience

Additional Context

• Tested on 2026-02-24 (original, tested filesystem discovery) and re-verified on 2026-03-09 (rerun explicitly tested system-reminder injection by instructing agents not to read files from disk). Both mechanisms confirmed.
• v2.1.32 changelog: "Skills in .claude/skills/ within --add-dir load automatically" — reinforces that filesystem-based skill discoverability is a design pattern, not a bug.
• Related issues:
• #29441 ("Agent skills: frontmatter not preloaded for team-spawned teammates") — closed as duplicate of #24780. Reports injection mechanism failing for teammates. Different angle: that issue is about injection not working; our issue is about docs implying discovery doesn't work either.
• #12633 ("Allow skills to be hidden from main agent") — feature request for subagent-exclusive skills, confirming that skill discoverability across contexts is a known design question.
• #27736 ("Agent skills field from frontmatter not rendered in Task tool agent description") — about UI rendering, not discoverability.