feat(agents): clarify mandatory YAML frontmatter for sub-agents (#16515)

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',
       );
     });
 

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---).',
     );
   }
 

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' +