[BUG] Agent skills: frontmatter not preloaded for team-spawned teammates #29441

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

When team orchestration spawns a teammate as a separate process, skills declared in the teammate's agent YAML frontmatter skills: field are silently ignored. The skills are neither preloaded into the conversation context nor injected as initial messages.

The same agent definition works correctly when spawned as an in-process subagent via the Task tool. The discrepancy arises because team orchestration spawns teammates as independent CLI processes (using internal, undocumented flags), and that process-level startup path does not consume the skills: field from the agent definition.

What Should Happen?

When team orchestration spawns a teammate, the teammate's skills: frontmatter should be processed identically to the in-process subagent path: each named skill should be resolved, loaded, and injected into the initial conversation context before the first turn.

Error Messages/Logs

Steps to Reproduce

1. Create a plugin agent with a skills: field in its YAML frontmatter:

   ---
   name: my-agent
   description: Agent with preloaded skills
   tools: "*"
   skills:
     - my-plugin:my-skill
   ---

2. Create the corresponding SKILL.md with a description: field in its frontmatter (required for skill discovery).

3. Spawn the agent as an in-process subagent via the Task tool:

   Use the Task tool with subagent_type "my-plugin:my-agent"
   

   Result: The skill content is preloaded into the conversation context as an initial message. The agent sees the skill instructions from its first turn.

4. Spawn the same agent as a team member (e.g., via TeamCreate and Task with team_name), so that team orchestration launches it as a separate process:
   Result: The agent starts without the skill content. The skills: frontmatter field is parsed and stored on the agent definition object, but never consumed by the process startup sequence.

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

No response

Claude Code Version

2.1.62

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

VS Code integrated terminal

Additional Information

Root Cause

The agent definition parser correctly reads the skills: array from YAML frontmatter and stores it on the agent definition object. However, there are two separate execution paths for agents, and only one of them consumes this field:

In-process subagent path (Task tool): The agent execution function iterates over agent.skills, resolves each skill name (with plugin-prefix fallback), loads the skill content via getPromptForCommand, and injects it into the initial messages array before the main loop begins.

Process-level startup path (team teammates): When team orchestration spawns a teammate as a separate CLI process, the startup sequence locates the agent definition in activeAgents, sets it as the mainThreadAgentDefinition, and uses it to derive the system prompt. However, the startup sequence never reads agent.skills. There is no code in this path that performs skill resolution, loading, or injection.

Impact

• Team orchestration is the primary consumer. Teammates spawned by a team leader rely on preloaded skills for domain context (repository conventions, implementation patterns, evaluation rubrics). Without preloading, the agent operates without the knowledge its author intended it to have.
• Silent failure. There is no diagnostic output indicating that skills were skipped. Plugin authors have no way to detect the problem short of observing that the teammate's behaviour does not reflect the skill content.
• Inconsistent behaviour. The same agent definition produces different results depending on whether it is spawned in-process (Task tool) or as a separate process (team orchestration). This violates the principle of least surprise.