{"record":{"id":"d207e319bc96dc20","repo":"google-gemini/gemini-cli","slug":"invalid-agent-definition-missing-mandatory-yaml-f","errorCode":null,"errorMessage":"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---).","messagePattern":"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---\\)\\.","errorType":"exception","errorClass":"AgentLoadError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agents/agentLoader.ts","lineNumber":350,"sourceCode":"): Promise<FrontmatterAgentDefinition[]> {\n  let fileContent: string;\n  if (content !== undefined) {\n    fileContent = content;\n  } else {\n    try {\n      fileContent = await fs.readFile(filePath, 'utf-8');\n    } catch (error) {\n      throw new AgentLoadError(\n        filePath,\n        `Could not read file: ${getErrorMessage(error)}`,\n      );\n    }\n  }\n\n  // Split frontmatter and body\n  const match = fileContent.match(FRONTMATTER_REGEX);\n  if (!match) {\n    throw new AgentLoadError(\n      filePath,\n      '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---).',\n    );\n  }\n\n  const frontmatterStr = match[1];\n  const body = match[2] || '';\n\n  let rawFrontmatter: unknown;\n  try {\n    rawFrontmatter = load(frontmatterStr);\n  } catch (error) {\n    throw new AgentLoadError(\n      filePath,\n      `YAML frontmatter parsing failed: ${getErrorMessage(error)}`,\n    );\n  }\n","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agents/agentLoader.ts#L332-L368","documentation":"parseAgentMarkdown requires every agent .md file to begin with YAML frontmatter delimited by triple-dashes. FRONTMATTER_REGEX must match; if the file starts with prose, BOM, whitespace, or a different delimiter, no match is found and this error names the exact required format. The message includes a concrete example to guide correction.","triggerScenarios":"The file begins with a markdown heading or paragraph instead of '---'; a UTF-8 BOM precedes the opening dashes; the file uses '~~~' or '===' delimiters; the file was saved as plain markdown without frontmatter; CRLF line endings shifted the delimiter.","commonSituations":"Authoring a new agent file from a generic markdown template; converting a prompt file to the agent format; editor auto-stripping leading '---'; copy-paste that dropped the opening fence.","solutions":["Ensure byte 0 of the file is '-' and the first line is exactly '---'.","Add the required frontmatter block: ---\\nname: my-agent\\n---.","Remove any BOM or leading whitespace before the opening fence.","Use an editor that shows invisible characters to confirm the delimiter."],"exampleFix":"# before - file starts with prose\nYou are a helpful agent.\n\n# after\n---\nname: my-agent\ndescription: A helpful agent\n---\nYou are a helpful agent.","handlingStrategy":"validation","validationCode":"function startsWithFrontmatter(content: string): boolean {\n  // First non-BOM, non-whitespace characters must be '---'\n  return /^\\uFEFF?\\s*---(\\r?\\n|$)/.test(content);\n}\nif (!startsWithFrontmatter(content)) {\n  throw new Error('Agent file must start with YAML frontmatter (---).');\n}\nawait parseAgentMarkdown(filePath, content);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Provide an agent-file template that begins with the frontmatter fence.","Lint agent files in CI for the leading '---'.","Configure editors to strip BOM and use LF endings for these files."],"tags":["agent-loader","frontmatter","format","authoring"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}