[BUG] Agent skills field from frontmatter not rendered in Task tool agent description
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
What's Wrong?
When a plugin defines agents with a skills field in YAML frontmatter, the skills list is not rendered in the agent
description visible to the main session's Task tool. The tools field (a peer field in the same frontmatter) renders
correctly, but skills is silently dropped.
The main session sees:
vfsbot:vfs-tl: simple description (Tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, ToolSearch)
No skills information is included, despite the agent frontmatter defining:
skills: [vfs-pm-framework]
The skills ARE correctly injected into the subagent's context at startup — confirmed by spawning the agent and asking it to
list its preloaded content. The issue is only with the description surfaced to the calling session.
What Should Happen?
The agent description in the Task tool should include the skills list alongside the tools list, e.g.:
vfsbot:vfs-tl: simple description (Tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, ToolSearch) (Skills:
vfs-pm-framework)
This allows the main session to write informed prompts and understand what domain knowledge each agent has preloaded.
Error Messages/Logs
Steps to Reproduce
Steps to Reproduce
- Create a Claude Code plugin with .claude-plugin/plugin.json
- Define an agent in agents/test-agent.md with the following frontmatter:
---
name: test-agent
description: "Test agent"
tools: [Read, Grep, Glob, Bash]
skills: [my-skill]
---
- Create a matching skill in skills/my-skill/SKILL.md:
---
name: my-skill
description: "A test skill"
user-invocable: false
---
Some skill content here.
- Start a Claude Code session in the plugin directory
- Observe the Task tool's available agent descriptions — the tools list appears but skills does not
- Spawn the agent and ask it to list preloaded skills — it confirms the skill content IS injected
Claude Model
Opus
Is this a regression?
I don't know
Last Working Version
_No response_
Claude Code Version
2.1.50
Platform
Anthropic API
Operating System
macOS
Terminal/Shell
Terminal.app (macOS)
Additional Information
This has a real impact on agent orchestration quality. Without knowing which skills an agent has, the main session has to
rely on external documentation or trial-and-error to write effective prompts. In our case, it caused 4 failed attempts
before successfully prompting a librarian agent to use its preloaded rag-tool skill — because the main session had no way to
know the skill existed on that agent.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗