claude-code - 💡(How to fix) Fix Subagent skills: frontmatter preload is skipped when the agent runs as the main session via --agent [2 comments, 3 participants]

Summary

The skills: frontmatter field on an agent is documented as preloading the full SKILL.md content into the agent's context at startup (sub-agents → Preload skills into subagents):

"The full content of each listed skill is injected into the subagent's context at startup."

In practice, this preload only fires when the agent is invoked as a subagent (via the Task tool / Agent dispatch). When the same agent file is invoked as the main session via --agent <name> or the agent setting, the listed skills' bodies are not preloaded — only their descriptions land in context, the same as in a regular session.

This is a meaningful gap because --agent is the intended path for shipping opinionated "personality" sessions (e.g., a popup-based dispatch agent for a plugin), where the agent needs its companion skills available without an extra Skill-tool round-trip per session.

Reproduction

Used the bundled agent-browser skill (~/.claude/skills/agent-browser/SKILL.md) and the browser-deep-research agent file (~/.claude/agents/browser-deep-research.md) whose frontmatter contains:

skills:
- agent-browser

In both cases, asked the model (no tool calls allowed) whether the agent-browser SKILL.md body is in its boot-time context.

Case A — subagent dispatch (works as documented)

Dispatched via Task tool with subagent_type: browser-deep-research. The subagent reports the agent-browser skill body is fully loaded and quotes the first content line verbatim.

Case B — same agent as main session via --agent (preload missing)

claude --agent browser-deep-research -p \
  "Without calling any tool: is the agent-browser skill body in your boot context?"

The model reports the skill body is not in context — only its description.

Same agent file, same skills: list, only the invocation path differs.

Expected behavior

Either:

• --agent (main session) preloads skills: the same way subagent dispatch does, matching the docs' "the full skill content is injected at startup" guarantee, or
• The docs explicitly carve out that skills: preload is subagent-only, and document a supported preload mechanism for the --agent main-session path.

Separately, it would also help to have a first-class CLI-level way to preload a list of skills at claude invocation time (e.g., a --preload-skills flag, or guaranteed slash-command processing of initialPrompt contents on the main-session path). Today the only options for a wrapper script that launches a popup-style session are side channels (--append-system-prompt[-file], SessionStart hook additionalContext) that live outside the Skill system and fragment the prompt cache when the model later invokes the same skill via the Skill tool.

Environment

• Claude Code: 2.1.144
• macOS: 26.3.1 (Darwin 25.3.0)