Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix skills: frontmatter field in custom agents does not inject skill content into subagent context [3 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#46311•Fetched 2026-04-11 06:23:39
View on GitHub
Comments
3
Participants
3
Timeline
7
Reactions
0
Author
100parik100parik
Participants
100parik100parikFearvoxFearvoxgithub-actions[bot]github-actions[bot]
Timeline (top)
labeled ×4commented ×3

The skills: frontmatter field in custom agent .md files does not inject skill content into the subagent's system prompt/context, despite documentation stating it should.

Root Cause

The skills: frontmatter field in custom agent .md files does not inject skill content into the subagent's system prompt/context, despite documentation stating it should.

Code Example

---
name: ui-ux-pro-max
description: "UI/UX design intelligence..."
---

# UI/UX Pro Max - Design Intelligence

Comprehensive design guide for web and mobile applications...

---

---
name: frontend
description: "Frontend agent..."
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
maxTurns: 30
skills:
  - ui-ux-pro-max
---

# Frontend Agent
You are a frontend agent with UI/UX skills.
RAW_BUFFERClick to expand / collapse

Description

The skills: frontmatter field in custom agent .md files does not inject skill content into the subagent's system prompt/context, despite documentation stating it should.

Steps to reproduce

  1. Create a skill at ~/.claude/skills/ui-ux-pro-max/SKILL.md with valid frontmatter:
---
name: ui-ux-pro-max
description: "UI/UX design intelligence..."
---

# UI/UX Pro Max - Design Intelligence

Comprehensive design guide for web and mobile applications...
  1. Create a custom agent at ~/.claude/agents/frontend.md:
---
name: frontend
description: "Frontend agent..."
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
maxTurns: 30
skills:
  - ui-ux-pro-max
---

# Frontend Agent
You are a frontend agent with UI/UX skills.

  1. Spawn the agent via Agent tool with subagent_type: "frontend"

  2. Ask the agent: "Do you see the content of skill ui-ux-pro-max in your context? Search for 'Comprehensive design guide'"

Expected behavior

Per documentation:

"The full content of each skill is injected into the subagent's context"

The subagent should have the full SKILL.md content in its system prompt.

Actual behavior

The subagent reports:

  • No skill content found in context
  • Only sees references to skill file paths from the agent's body text
  • Skill tool is not available to the subagent
  • Specific strings from SKILL.md ("Comprehensive design guide", "161 color palettes", "bento grid") are not present

Environment

  • Claude Code: latest (as of 2026-04-10)
  • OS: Ubuntu 24.04
  • Model: opus (parent) → sonnet (subagent)
  • Skill location: ~/.claude/skills/ui-ux-pro-max/SKILL.md
  • Agent location: ~/.claude/agents/frontend.md

extent analysis

TL;DR

The issue may be resolved by verifying the skill file path and name in the agent's frontmatter, ensuring it matches the actual skill file location and name.

Guidance

  • Check the skills field in the agent's frontmatter to ensure it correctly references the skill file ui-ux-pro-max.
  • Verify that the skill file SKILL.md is located in the correct directory ~/.claude/skills/ui-ux-pro-max/ and that the file name matches the one specified in the agent's frontmatter.
  • Review the documentation to ensure that the skills field in the agent's frontmatter is correctly formatted and that the skill file content is correctly injected into the subagent's context.
  • Test the agent with a different skill to determine if the issue is specific to the ui-ux-pro-max skill or a more general problem.

Example

No code snippet is provided as the issue seems to be related to configuration and file paths rather than code.

Notes

The issue may be related to a configuration or file path issue rather than a code problem. Further investigation is needed to determine the root cause.

Recommendation

Apply workaround: Verify and correct the skill file path and name in the agent's frontmatter to ensure it matches the actual skill file location and name, as this is the most likely cause of the issue.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

Per documentation:

"The full content of each skill is injected into the subagent's context"

The subagent should have the full SKILL.md content in its system prompt.

#embedding generation#cache error#pipeline error#runtime error#dependency conflict

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING