[DOCS] Skill tool not available in Plan mode — unclear which tools Plan subagent can use

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:

1. The Skill tool is intentionally excluded from the Plan subagent
2. This is a bug — a read-only skill should be invocable in Plan mode
3. 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

1. 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, ...

1. 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.

1. 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.