Agent Field: 10 Questions Answered

1. Mechanics

How does it work?

• agent field in frontmatter specifies Task tool agent type
• Valid values: Explore, Plan, general-purpose, Bash, claude-code-guide
• Invalid values (like haiku, sonnet) are silently ignored

What triggers it?

• Skill invocation with agent field routes to specified agent type
• Combined with context: fork for isolated execution

Implementation model (guess):

• Skill system maps agent field to Task tool subagent dispatch
• Agent type determines model tier (Explore→Haiku, Plan→Opus)

2. Model/Agent

What model runs?

Agent Type	Model
Explore	Haiku
Plan	Opus
general-purpose	Opus

Can you specify model directly?

• No - agent: haiku is ignored
• Must use agent type, model follows

Default behavior:

• No agent field → runs in current context (same model as parent)
• Invalid agent field → same as no field

3. Context

Fresh or inherited?

• With context: fork → fresh context
• Without fork → unclear, likely inherited

What carries over:

• With fork: system context only (project info, date)
• Without fork: likely full conversation

4. Tool Access

Default tools:

• Determined by agent type
• Explore: Glob, Grep, Read (search-focused)
• Plan: All planning tools
• Can override with allowed-tools

Restrictions:

• Agent types may have built-in restrictions
• allowed-tools can further restrict

5. Failure Modes

Invalid agent type:

• Silently ignored
• Falls back to default behavior
• No error surfaced

Agent type mismatch:

• Using Explore for complex reasoning = poor results
• Using Plan for simple search = wasted tokens

6. Performance

Latency:

• Depends on agent type model
• Haiku (Explore) faster than Opus (Plan)

Token cost:

• Haiku ~15x cheaper than Opus
• Significant savings for frequent skills

Parallelism:

• Multiple skills with agent: Explore could run parallel
• Need to test actual parallel invocation

7. Feature Interactions

With context: fork:

• Recommended combination
• Fork isolates, agent routes to model
• Together = cheap isolated execution

With hot-reload:

• Works - can modify agent field and re-invoke
• Changes picked up immediately

With allowed-tools:

• Can combine to restrict tool access
• Agent type sets base, allowed-tools restricts further

8. Edge Cases Tested

Scenario	Result
agent: Explore	Haiku model
agent: Plan	Opus model
agent: general-purpose	Opus model
agent: haiku (invalid)	Ignored, Opus
agent: sonnet (invalid)	Not tested, likely ignored
No agent field	Parent model
Agent + fork	Works together

9. Security

Trust boundary:

• Agent type may limit capabilities
• Bash agent likely sandboxed differently
• Explore agent read-focused

Model trust:

• Cheaper models (Haiku) may be less careful
• Security-critical tasks should use capable models

10. Debugging

How to verify agent routing:

• Skill can self-report model from system prompt
• Check for model ID in output

Common issues:

• Invalid agent type silently ignored
• Expecting model names to work (they don't)

---

Key Finding

Agent field enables cost-optimized skill routing:

• Use agent: Explore for research/search → Haiku prices
• Use agent: Plan for architecture → Opus quality
• Invalid values fail silently - always test

Combined with context: fork, this unlocks cheap parallel execution pattern.

Use Cases: Agent Field in Skills

Feature: agent field in skill frontmatter specifies agent type for execution

---

Core Value Proposition

Different tasks need different capabilities:

• Research → fast, cheap, good enough
• Architecture → slow, expensive, best quality
• Bash operations → specialized, sandboxed

The agent field lets you match task to capability tier without hard-coding models.

---

Use Cases

1. Cost-Optimized Research Skills

Scenario: You need to search/grep/read across a codebase frequently.

---
name: find-usages
agent: Explore
context: fork
allowed-tools: Grep,Glob,Read
---

Impact: Each invocation runs Haiku instead of Opus. For frequent research tasks, this adds up.

Math: If Opus is ~15x more expensive than Haiku, and you run 20 research skills per session, you save ~95% on those operations.

---

2. Tiered Skill Pipelines

Scenario: Complex workflow where some stages need smarts, others just need speed.

Stage 1: Gather data (agent: Explore) → Haiku
Stage 2: Analyze patterns (agent: general-purpose) → Opus
Stage 3: Format output (agent: Explore) → Haiku

Impact: Only pay for expensive reasoning where it matters.

---

3. Parallel Cheap Exploration

Scenario: Need to search multiple areas of a codebase simultaneously.

# skill-a
agent: Explore
context: fork
# searches area A

# skill-b
agent: Explore
context: fork
# searches area B

Impact: Both run on Haiku in parallel (if supported), orchestrator synthesizes.

---

4. Fail-Fast Validation

Scenario: Quick check before expensive operation.

---
name: pre-check
agent: Explore
context: fork
---
# Quick validation - is this file even relevant?
# If not, don't waste Opus tokens on full analysis

Impact: Cheap triage saves expensive mistakes.

---

5. Agent-Type Specialization

Scenario: Use agent types for their designed purpose.

Task	Agent	Why
Find files	Explore	Optimized for search
Design system	Plan	Optimized for architecture
Run commands	Bash	Sandboxed execution
General work	general-purpose	Full capability

Impact: Right tool for the job, not just cost optimization.

---

6. Safe Experimentation

Scenario: Testing new skill designs without burning tokens.

---
name: experiment-v1
agent: Explore
context: fork
---

While iterating on skill design, use cheap model. Switch to Plan or general-purpose when finalized.

---

7. Budget-Constrained Environments

Scenario: CI/CD or automated systems with token budgets.

# All CI skills use Explore unless they need planning
agent: Explore

Impact: Predictable costs, automated systems don't need Opus-level reasoning for most checks.

---

Anti-Patterns

1. Over-Optimizing

Don't use agent: Explore for tasks that need real reasoning. Haiku will give worse results on complex analysis.

2. Ignoring Agent Capabilities

Each agent type has specific tools/behaviors. Bash agent is different from Explore. Match task to agent type, not just cost.

3. Invalid Agent Values

agent: haiku doesn't work - it's ignored. Use valid Task tool agent types.

---

Agent Type Reference

Agent Type	Model	Best For
Explore	Haiku	File search, grep, quick reads
Plan	Opus	Architecture, design decisions
general-purpose	Opus	Complex multi-step tasks
Bash	?	Shell command execution
claude-code-guide	?	Documentation lookups

(Some agent types not tested yet)

---

Key Insight

Agent field is about capability routing, not just cost:

• Pick agent type based on task requirements
• Cost savings follow naturally
• Invalid values fail silently (use valid types!)