Summary
When a custom agent definition (.claude/agents/<name>.md) is used to spawn a team agent (via the Agent tool with team_name parameter), all frontmatter fields and the markdown body (system prompt) are silently ignored. Only model and agent_type (in SubagentStart/SubagentStop hooks) work correctly.
The same custom agent definitions work fully when spawned as pure subagents (without team_name).
Reproduction
- Create
.claude/agents/my-agent.md:
---
name: my-agent
description: Test agent with baked-in identity.
model: opus
hooks:
PreToolUse:
- matcher: ""
hooks:
- type: command
command: echo "hook fired"
skills:
- my-skill
disallowedTools: Write, Edit
---
# You are: My Agent
You have a specific identity and instructions baked in.
- Spawn as pure subagent (works correctly):
Agent(subagent_type="my-agent", prompt="What is your role?")
→ Agent receives the markdown body as system prompt, hooks fire, model is applied.
- Spawn as team agent (broken):
Agent(subagent_type="my-agent", team_name="my-team", name="team-agent" prompt="What is your role?")
→ Agent has NO custom system prompt. Only project-wide rules (.claude/rules/) and CLAUDE.md files are loaded. Agent cannot identify itself.
What is silently ignored for team agents
| Feature |
Pure subagent |
Team agent |
| System prompt (markdown body) |
✅ Works |
✅ Works |
skills frontmatter |
✅ Works |
❌ Silently ignored (known: #29441 / #24780) |
disallowedTools frontmatter |
✅ Works |
✅ Works |
Frontmatter hooks |
✅ Works |
❌ Silently ignored |
model frontmatter |
✅ Works |
✅ Works |
agent_type in SubagentStart/Stop |
✅ Works |
✅ Works |
Impact
This makes custom agent definitions nearly useless for team-based workflows. Teams cannot:
- Bake role identity into agents (must use spawn prompt instead)
- Enforce tool restrictions via
disallowedTools
- Attach lifecycle hooks to specific agent types
- Preload skills into team agents
The silent failure is particularly problematic — there are no warnings or errors. Users may believe their agent definitions are being applied when they are not.
Environment
- Claude Code version: 2.1.68
- Platform: macOS (Darwin 24.5.0, arm64)
- Agent teams enabled via
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Related issues
Summary
When a custom agent definition (
.claude/agents/<name>.md) is used to spawn a team agent (via the Agent tool withteam_nameparameter), all frontmatter fields and the markdown body (system prompt) are silently ignored. Onlymodelandagent_type(in SubagentStart/SubagentStop hooks) work correctly.The same custom agent definitions work fully when spawned as pure subagents (without
team_name).Reproduction
.claude/agents/my-agent.md:→ Agent receives the markdown body as system prompt, hooks fire, model is applied.
→ Agent has NO custom system prompt. Only project-wide rules (
.claude/rules/) andCLAUDE.mdfiles are loaded. Agent cannot identify itself.What is silently ignored for team agents
skillsfrontmatterdisallowedToolsfrontmatterhooksmodelfrontmatteragent_typein SubagentStart/StopImpact
This makes custom agent definitions nearly useless for team-based workflows. Teams cannot:
disallowedToolsThe silent failure is particularly problematic — there are no warnings or errors. Users may believe their agent definitions are being applied when they are not.
Environment
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1Related issues
skills:frontmatter not preloaded for team-spawned teammates #29441 / [BUG] Bug: Teammates do NOT load skills despite documentation stating they do #24780:skillsfield silently ignored for team agents (subset of this bug)