skills: frontmatter field in custom agents does not inject skill content into subagent context

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/25834
2. https://github.com/anthropics/claude-code/issues/35054
3. https://github.com/anthropics/claude-code/issues/31514

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

This is not a duplicate of the suggested issues. Here's why:

• #25834 (closed as completed) — reports that plugin-level skills fail to inject into plugin agents. Their own testing confirmed that project/user-level skills DO inject correctly into project-level agents. Our issue is the opposite: user-level skill (~/.claude/skills/) + user-level agent (~/.claude/agents/) = no injection.

• #35054 (open) — specifically about context: fork and plugin-loaded skills being silently ignored. Our issue doesn't involve plugins or context: fork at all.

• #31514 (closed as not_planned) — about Skill tool not being available to subagents. Related but different — we're reporting that the skills: frontmatter field doesn't inject content, not that a tool is missing.

Our specific case

| Component | Location | Level |
|---|---|---|
| Agent | ~/.claude/agents/frontend.md | User |
| Skill | ~/.claude/skills/ui-ux-pro-max/SKILL.md | User |
| Working dir | /home/denis | — |

Verification method

1. Created agent with skills: [ui-ux-pro-max] in frontmatter
2. Spawned the agent and asked it to search for unique strings from SKILL.md
3. Agent confirmed: no skill content in context — only the body text of the agent .md file is present
4. Additionally tested with a throwaway skill containing UNIQUE_TEST_STRING_PINEAPPLE_ROCKET_777 — also not injected

Key difference from #25834

Issue #25834 author explicitly confirmed that project-level agent + project-level skill works. Our case uses user-level (~/.claude/) for both agent and skill — and it does not work. This suggests the bug scope is wider than just plugins.

Confirming this is still reproducible and adding context.

Our findings from parallel Agent dispatch workflows:

The root cause you identified (skill content not injected into subagent context) describes exactly what we observed. Additional observations:

1. Skills loaded via frontmatter in agents are also affected — not just top-level skill loading. If an agent uses skills: frontmatter to load a skill, the subagent that agent spawns does not receive that skill's content.

1. The workaround (manually passing skill content as instruction) works but defeats the purpose — the whole value of the skills: frontmatter is declarative injection, which should propagate to subagents automatically.

1. Cache timing issue compounds this: Even when skills ARE correctly injected initially, long-running subagents can fail to reload context from cache properly on resume, causing the same "skill not found" behavior.

This is critical for agent teams workflows where multiple specialized agents need shared skill context.

Affected path: src/tools/AgentTool/runAgent.ts → skill loading → subagent context injection

Update — cannot reproduce on Claude Code 2.1.139, please close as fixed

Re-ran the repro on a clean test today (2026-05-12) on claude --version → 2.1.139. The skills: frontmatter injection now works as the sub-agents documentation describes.

Test setup (sentinel-based, no original skill involved)

To rule out any false negative from ui-ux-pro-max being a large file, I built a minimal sentinel skill whose body contains strings that exist nowhere else on disk:

~/.claude/skills/repro46311/SKILL.md:

---
name: repro46311
description: Repro test skill for claude-code issue 46311. Sentinel-based skill injection verification.
---

# Repro 46311 — Sentinel Skill

The following sentinels appear ONLY in this body:

- `SENTINEL_BODY_ALPHA_PAPAYA_8421`
- `SENTINEL_BODY_BETA_TURBINE_9907`
- `SENTINEL_BODY_GAMMA_OBSIDIAN_3315`

~/.claude/agents/repro46311.md:

---
name: repro46311
description: Repro agent for claude-code issue 46311. Verifies whether skills frontmatter injection works.
tools: Read, Grep, Glob, Bash
model: sonnet
skills:
  - repro46311
---

# Repro 46311 Agent

You are a diagnostic agent. Your only job is to introspect your own initial
context and report whether the `skills:` frontmatter mechanism injected skill
body content into your system prompt.

Result

Dispatching the subagent and asking it (without giving it disk access first) whether it sees the three sentinels in its system prompt:

• SENTINEL_BODY_ALPHA_PAPAYA_8421 → YES
• SENTINEL_BODY_BETA_TURBINE_9907 → YES
• SENTINEL_BODY_GAMMA_OBSIDIAN_3315 → YES
• Title # Repro 46311 — Sentinel Skill → YES

Cross-check against the original repro: a second subagent (frontend) with skills: [ui-ux-pro-max] was also asked to find the string "Comprehensive design guide" from ui-ux-pro-max/SKILL.md — it is present in its context. So the original failure mode (body strings absent) does not reproduce either.

Matches documented behavior

The sub-agents docs state:

"The full content of each listed skill is injected into the subagent's context at startup. This field controls which skills are preloaded, not which skills the subagent can access."

That is exactly what we now observe. This is the inverse of how main-agent skills work (description-only in context, body loaded on Skill tool invocation).

Caveats worth documenting (not blocking close)

1. Only SKILL.md is injected, not the rest of the skill folder. data/, references/, assets/ are not preloaded — the subagent has to Read them on demand. This may surprise users porting skills that rely on supporting files.
2. The subagent's view of the list of other available skills (the description-only list main agents get) appears different from the main agent's. Not tested rigorously, just noting.

Likely fix lineage

The changelog entry for v2.1.133 (2026-05-07) — "Fixed subagents not discovering project, user, or plugin skills via the Skill tool" — is about Skill-tool discovery, but it's the closest user-facing entry to this area and the behavior shift seems to have landed around the same window.

Ask

Since the reproduction no longer triggers on 2.1.139 and behavior now matches the docs, I'd suggest closing this as fixed. Happy to retest on whichever earlier version maintainers want pinned as the fix point if that's useful for the changelog.

Also marking the previously linked duplicates as worth a quick re-check:

• #25834
• #35054
• #31514

This issue was fixed as of version v2.1.139.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.