Claude Code v2.1.9x added initialPrompt as a supported frontmatter field for subagent configuration files. When present, it auto-submits as the first turn when the subagent is spawned — no manual kickstart required. Here’s how to use it effectively.

What initialPrompt Does

In a Claude Code subagent configuration file (typically a CLAUDE.md or equivalent file that defines the agent’s role and behavior), you can now include a YAML frontmatter block at the very top. The initialPrompt key in that block is auto-submitted as the agent’s first message when it’s spawned.

Without initialPrompt:

  1. Parent agent spawns subagent
  2. Parent agent sends task message
  3. Subagent begins working

With initialPrompt:

  1. Parent agent spawns subagent
  2. Subagent begins working immediately (task is in the config file)

The parent agent doesn’t need to relay context. The subagent is born knowing its job.

Basic Setup

Add a YAML frontmatter block to the top of your subagent’s CLAUDE.md file:

---
name: searcher-agent
description: Searches for and aggregates news on a given topic
initialPrompt: "You are the Searcher agent. Your run folder is at the path specified in SOUL.md. Read your SOUL.md file now and begin your assigned search task."
---

# Searcher Agent

You are a specialized search agent...

The --- delimiters must be the very first characters in the file. Any content before the frontmatter will cause it to be ignored.

Using Template Variables

initialPrompt supports template variables that are resolved at spawn time, not at config-write time. This is the key feature that makes initialPrompt useful for dynamic pipelines.

Available template variables (as documented in the Claude Code sub-agents docs):

  • {{run_id}} — the run ID passed to the spawned agent
  • {{run_folder}} — the absolute path to the current run folder
  • {{parent_agent}} — the name/ID of the spawning agent
  • {{timestamp}} — ISO 8601 timestamp at spawn time
  • {{session_id}} — the session ID of the spawned agent

Example with template variables:

---
name: writer-agent
description: Writes articles from analyst handoff data
initialPrompt: "Your run ID is {{run_id}}. Run folder: {{run_folder}}. Follow your SOUL.md instructions exactly."
---

When the parent agent spawns this subagent, {{run_id}} and {{run_folder}} are resolved from the spawn parameters. The subagent’s first turn already contains the context it needs.

This is the pattern used by production pipelines where the orchestrator passes a run ID and folder path to each stage: the initialPrompt template handles context injection automatically.

Full Working Example: A Pipeline Stage Agent

Here’s a complete subagent configuration using initialPrompt with template variables:

---
name: analyst-agent
description: Analyzes and filters search results from the Searcher stage
version: "1.0"
initialPrompt: |
  Your run ID is {{run_id}}.
  Run folder: {{run_folder}}.
  
  Read handoff_searcher_to_analyst.md in your run folder now.
  Follow your SOUL.md instructions exactly to produce handoff_analyst_to_writer.md.
---

# Analyst Agent — subagentic.ai Pipeline

You are the Analyst agent in the subagentic.ai content pipeline...

The | (block scalar) syntax allows multi-line initialPrompt values. Each line is preserved as-is.

How the Parent Agent Spawns With Template Resolution

When the parent agent spawns this subagent via Claude Code’s agent spawning mechanism, it passes the run parameters that resolve the template variables:

Your run ID is subagentic-20260405-0800. Run folder: ~/subagentic-pipeline/pipeline/runs/current-run-subagentic-20260405-0800/. Follow your SOUL.md instructions exactly.

(This is the actual task prompt used in the subagentic.ai pipeline — the orchestrator spawns each stage agent with the run ID and folder, and the initialPrompt template resolves those values into a complete first turn.)

Combining initialPrompt With Other Frontmatter Fields

initialPrompt is one of several supported frontmatter fields. A complete agent configuration might include:

---
name: my-agent
description: What this agent does (shown in agent discovery)
version: "1.2"
model: claude-opus-4-6          # optional: override default model
max_turns: 50                   # optional: limit agent turn count
initialPrompt: "{{run_id}} — begin task."
---

The model override is particularly useful when combined with initialPrompt: you can configure a subagent to always use Opus for complex reasoning tasks, with its first turn auto-submitted so it starts thinking immediately.

Troubleshooting

initialPrompt is not being auto-submitted: Verify the YAML frontmatter block starts at line 1 of the file with ---. Any content before the block (including blank lines) will prevent frontmatter parsing.

Template variables are not resolving: Check that the parent agent is passing the parameters when it spawns the subagent. Template variables that don’t have a matching spawn parameter will be left as-is (not removed), which may cause the agent to receive literal {{run_id}} text.

Multi-line initialPrompt has formatting issues: Use the | block scalar for multi-line values. The > folded scalar will collapse newlines, which may not be what you want.

Related: Claude Code v2.1.9x release overview · Claude Code sub-agents documentation