Documentation Type
Unclear/confusing documentation
Documentation Location
https://code.claude.com/docs/en/sub-agents.md
Section/Topic
Built-in subagents - Plan subagent tool availability, specifically the Skill tool
Current Documentation
The Plan subagent section says:
Tools: Read-only tools (denied access to Write and Edit tools)
What's Wrong or Missing?
I have a read-only skill that only performs research and analysis — no writes, no edits. Its frontmatter:
---
name: codebase-analysis-planner
description: Analyzes codebase and prepares a structured refactoring plan
model: sonnet
---
The skill body only uses read-only operations: code search, LSP lookups, Read/Grep tools, and outputs a structured analysis plan. It explicitly focuses on planning only — no code changes.
When I enter Plan mode, this skill does not get invoked. Since the docs only say "read-only tools (denied access to Write and Edit tools)" without an explicit tool list, I can't determine whether:
- The
Skill tool is intentionally excluded from the Plan subagent
- This is a bug — a read-only skill should be invocable in Plan mode
- There's a workaround (e.g., preloading the skill via the
skills frontmatter field on a custom Plan-like subagent)
The docs need to explicitly list which tools are available to the Plan subagent so users can understand what's possible and design their skills/workflows accordingly.
Suggested Improvement
-
Enumerate the exact tool list for each built-in subagent. For example:
Plan
- Available tools: Read, Glob, Grep, AskUserQuestion, ...
- Denied tools: Write, Edit, Task, Skill, Bash, NotebookEdit, ...
-
Document Skill tool behavior in Plan mode — if skills are not available in Plan mode, mention this in the Skills docs as a known limitation or suggest the skills frontmatter preload approach as an alternative.
-
Clarify the workaround — if the intended path is to use the skills field in a custom subagent's frontmatter to preload skill content, document this pattern explicitly for users who want skill-like behavior in plan/read-only contexts.
Impact
Medium - Makes feature difficult to understand
Additional Context
The skill is part of a plugin and is designed specifically for planning workflows — making it a natural fit for Plan mode. The inability to use it there, combined with ambiguous docs, makes it hard to build effective read-only skills for planning use cases.
Documentation Type
Unclear/confusing documentation
Documentation Location
https://code.claude.com/docs/en/sub-agents.md
Section/Topic
Built-in subagents - Plan subagent tool availability, specifically the Skill tool
Current Documentation
The Plan subagent section says:
What's Wrong or Missing?
I have a read-only skill that only performs research and analysis — no writes, no edits. Its frontmatter:
The skill body only uses read-only operations: code search, LSP lookups, Read/Grep tools, and outputs a structured analysis plan. It explicitly focuses on planning only — no code changes.
When I enter Plan mode, this skill does not get invoked. Since the docs only say "read-only tools (denied access to Write and Edit tools)" without an explicit tool list, I can't determine whether:
Skilltool is intentionally excluded from the Plan subagentskillsfrontmatter field on a custom Plan-like subagent)The docs need to explicitly list which tools are available to the Plan subagent so users can understand what's possible and design their skills/workflows accordingly.
Suggested Improvement
Enumerate the exact tool list for each built-in subagent. For example:
Document Skill tool behavior in Plan mode — if skills are not available in Plan mode, mention this in the Skills docs as a known limitation or suggest the
skillsfrontmatter preload approach as an alternative.Clarify the workaround — if the intended path is to use the
skillsfield in a custom subagent's frontmatter to preload skill content, document this pattern explicitly for users who want skill-like behavior in plan/read-only contexts.Impact
Medium - Makes feature difficult to understand
Additional Context
The skill is part of a plugin and is designed specifically for planning workflows — making it a natural fit for Plan mode. The inability to use it there, combined with ambiguous docs, makes it hard to build effective read-only skills for planning use cases.