[DOCS] Document `initialPrompt` frontmatter field for agents (auto-submits a first turn)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

"Supported frontmatter fields" table (under "Write subagent files")

Current Documentation

The "Supported frontmatter fields" table lists these fields for agent .md files:

| Field | Required | Description |
| :---------------- | :------- | :------------------------------------------------ |
| name | Yes | Unique identifier using lowercase letters and hyphens |
| description | Yes | When Claude should delegate to this subagent |
| tools | No | Tools the subagent can use |
| disallowedTools | No | Tools to deny |
| model | No | Model to use |
| permissionMode | No | Permission mode |
| maxTurns | No | Maximum number of agentic turns |
| skills | No | Skills to load into the subagent's context |
| mcpServers | No | MCP servers available to this subagent |
| hooks | No | Lifecycle hooks scoped to this subagent |
| memory | No | Persistent memory scope |
| background | No | Run as a background task |
| effort | No | Effort level override |
| isolation | No | Run in an isolated git worktree |

The --agents flag documentation also enumerates the supported fields and does not include initialPrompt.

What's Wrong or Missing?

Claude Code v2.1.83 added an initialPrompt frontmatter field for agent files. When set, it auto-submits a first turn on behalf of the user when the agent starts, eliminating the need for users to type an opening message. This field is not mentioned anywhere in the current documentation:

• The "Supported frontmatter fields" table in sub-agents does not list initialPrompt.
• The --agents JSON flag documentation does not include it in its field enumeration.
• No docs page explains what the field does, what values it accepts, or provides a usage example.

Source: Changelog v2.1.83 — "Agents can now declare initialPrompt in frontmatter to auto-submit a first turn"

Suggested Improvement

Add initialPrompt to the "Supported frontmatter fields" table in the sub-agents documentation:

| Field | Required | Description |
| :-------------- | :------- | :------------------------------------------------------------------------------------------------ |
| initialPrompt | No | A message auto-submitted as the first user turn when the agent starts, so users don't need to type an opening message |

Add a brief prose section or note near the table explaining the field's purpose and showing an example:

---
name: code-reviewer
description: Review code for quality and correctness
initialPrompt: Review the most recently changed files and summarize any issues found.
---

You are a code review assistant. Focus on correctness, readability, and test coverage.

Also update the --agents flag field enumeration (line: "The --agents flag accepts JSON with the same frontmatter fields…") to include initialPrompt.

Impact

High - Prevents users from using a feature

Additional Context

Affected pages:

• https://code.claude.com/docs/en/sub-agents (primary — "Supported frontmatter fields" table and --agents flag section)

Source: Changelog v2.1.83 — "Agents can now declare initialPrompt in frontmatter to auto-submit a first turn"