google-gemini/gemini-cli · error · AgentLoadError

Invalid agent definition: Missing mandatory YAML frontmatter

Error message

Invalid agent definition: Missing mandatory YAML frontmatter. Agent Markdown files MUST start with YAML frontmatter enclosed in triple-dashes "---" (e.g., ---
name: my-agent
---).

What it means

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.

Source

Thrown at packages/core/src/agents/agentLoader.ts:350

): Promise<FrontmatterAgentDefinition[]> {
  let fileContent: string;
  if (content !== undefined) {
    fileContent = content;
  } else {
    try {
      fileContent = await fs.readFile(filePath, 'utf-8');
    } catch (error) {
      throw new AgentLoadError(
        filePath,
        `Could not read file: ${getErrorMessage(error)}`,
      );
    }
  }

  // Split frontmatter and body
  const match = fileContent.match(FRONTMATTER_REGEX);
  if (!match) {
    throw new AgentLoadError(
      filePath,
      '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---).',
    );
  }

  const frontmatterStr = match[1];
  const body = match[2] || '';

  let rawFrontmatter: unknown;
  try {
    rawFrontmatter = load(frontmatterStr);
  } catch (error) {
    throw new AgentLoadError(
      filePath,
      `YAML frontmatter parsing failed: ${getErrorMessage(error)}`,
    );
  }

View on GitHub (pinned to 5024443c72)

Solutions

1. Ensure byte 0 of the file is '-' and the first line is exactly '---'.
2. Add the required frontmatter block: ---\nname: my-agent\n---.
3. Remove any BOM or leading whitespace before the opening fence.
4. Use an editor that shows invisible characters to confirm the delimiter.

Example fix

# before - file starts with prose
You are a helpful agent.

# after
---
name: my-agent
description: A helpful agent
---
You are a helpful agent.

function startsWithFrontmatter(content: string): boolean {
  // First non-BOM, non-whitespace characters must be '---'
  return /^\uFEFF?\s*---(\r?\n|$)/.test(content);
}
if (!startsWithFrontmatter(content)) {
  throw new Error('Agent file must start with YAML frontmatter (---).');
}
await parseAgentMarkdown(filePath, content);

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• YAML frontmatter parsing failed: ${getErrorMessage(error)}
• No valid skills found in ${source}${subpath ? ` at path "${s
• Invalid skill name: Path traversal detected.
• Could not read file: ${getErrorMessage(error)}
• Validation failed: ${formatZodError(result.error, 'Remote Ag

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/d207e319bc96dc20. Report an issue: GitHub.