From 8faa23cea6c67fb75740a53f333f2de8f4656371 Mon Sep 17 00:00:00 2001 From: "N. Taylor Mullen" Date: Tue, 13 Jan 2026 09:44:52 -0800 Subject: [PATCH] feat(agents): clarify mandatory YAML frontmatter for sub-agents (#16515) --- packages/core/src/agents/agentLoader.test.ts | 2 +- packages/core/src/agents/agentLoader.ts | 2 +- packages/core/src/agents/cli-help-agent.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/core/src/agents/agentLoader.test.ts b/packages/core/src/agents/agentLoader.test.ts index eb642a7eb5..199d715fe9 100644 --- a/packages/core/src/agents/agentLoader.test.ts +++ b/packages/core/src/agents/agentLoader.test.ts @@ -83,7 +83,7 @@ System prompt content.`); AgentLoadError, ); await expect(parseAgentMarkdown(filePath)).rejects.toThrow( - 'Invalid markdown format', + 'Missing mandatory YAML frontmatter', ); }); diff --git a/packages/core/src/agents/agentLoader.ts b/packages/core/src/agents/agentLoader.ts index 5a65f03218..f8283c1933 100644 --- a/packages/core/src/agents/agentLoader.ts +++ b/packages/core/src/agents/agentLoader.ts @@ -163,7 +163,7 @@ export async function parseAgentMarkdown( if (!match) { throw new AgentLoadError( filePath, - 'Invalid markdown format. File must start with YAML frontmatter enclosed in "---".', + 'Invalid agent definition: Missing mandatory YAML frontmatter. Agent Markdown files MUST start with YAML frontmatter enclosed in triple-dashes "---" (e.g., ---\nname: my-agent\n---).', ); } diff --git a/packages/core/src/agents/cli-help-agent.ts b/packages/core/src/agents/cli-help-agent.ts index cf65819252..ea6709ca86 100644 --- a/packages/core/src/agents/cli-help-agent.ts +++ b/packages/core/src/agents/cli-help-agent.ts @@ -78,7 +78,7 @@ export const CliHelpAgent = ( "- **Today's Date:** ${today}\n\n" + (config.isAgentsEnabled() ? '### Sub-Agents (Local & Remote)\n' + - "User defined sub-agents are defined in `.gemini/agents/` or `~/.gemini/agents/` as .md files. These files contain YAML frontmatter for metadata, and the Markdown body becomes the agent's system prompt (`system_prompt`). Always reference the types and properties outlined here directly when answering questions about sub-agents.\n" + + "User defined sub-agents are defined in `.gemini/agents/` or `~/.gemini/agents/` as .md files. **CRITICAL:** These files **MUST** start with YAML frontmatter enclosed in triple-dashes `---`, for example:\n\n```yaml\n---\nname: my-agent\n---\n```\n\nWithout this mandatory frontmatter, the agent will not be discovered or loaded by Gemini CLI. The Markdown body following the frontmatter becomes the agent's system prompt (`system_prompt`). Always reference the types and properties outlined here directly when answering questions about sub-agents.\n" + '- **Local Agent:** `kind = "local"`, `name`, `description`, `system_prompt`, and optional `tools`, `model`, `temperate`, `max_turns`, `timeout_mins`.\n' + '- **Remote Agent (A2A):** `kind = "remote"`, `name`, `agent_card_url`. Remote Agents do not use `system_prompt`. Multiple remote agents can be defined by using a YAML array at the top level of the frontmatter. **Note:** When users ask about "remote agents", they are referring to this Agent2Agent functionality, which is completely distinct from MCP servers.\n' + '- **Agent Names:** Must be valid slugs (lowercase letters, numbers, hyphens, and underscores only).\n' +