continuedev/continue · error · Error

Agent file must contain YAML frontmatter with a 'name' field

Error message

Agent file must contain YAML frontmatter with a 'name' field

What it means

parseAgentFile splits an agent markdown file into frontmatter and prompt; if the YAML frontmatter lacks a 'name' key, the file is rejected before schema validation even runs.

Source

Thrown at packages/config-yaml/src/markdown/agentFiles.ts:52

 */
export interface ParsedAgentTools {
  /** All tool references */
  tools: AgentToolReference[];
  /** Unique MCP server slugs that need to be added to config */
  mcpServers: string[];
  /** Whether all built-in tools are allowed */
  allBuiltIn: boolean;
}

/**
 * Parses and validates an agent file from markdown content
 * Agent files must have frontmatter with at least a name
 */
export function parseAgentFile(content: string): AgentFile {
  const { frontmatter, markdown } = parseMarkdownRule(content);

  if (!frontmatter.name) {
    throw new Error(
      "Agent file must contain YAML frontmatter with a 'name' field",
    );
  }

  const validationResult = agentFileFrontmatterSchema.safeParse(frontmatter);

  if (!validationResult.success) {
    const errorDetails = validationResult.error.issues
      .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
      .join(", ");
    throw new Error(`Invalid agent file frontmatter: ${errorDetails}`);
  }

  return {
    ...validationResult.data,
    prompt: markdown,
  };
}

View on GitHub (pinned to 5522c6f44c)

Solutions

1. Add YAML frontmatter at the top delimited by --- with at least 'name: your-agent-name'
2. Verify the delimiters: opening --- must be the very first line
3. Confirm the frontmatter is valid YAML (no tabs)

Example fix

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

function hasNameFrontmatter(content: string): boolean {
  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
  return !!m && /^name\s*:/m.test(m[1]);
}

try { parseAgentFile(content); } catch (e) { if (e.message.includes('name')) { /* add frontmatter */ } }

When it happens

Trigger: parseAgentFile(content) where content has no frontmatter block, empty frontmatter (---\n---), or frontmatter without a name field.

Common situations: Writing an agent file as plain markdown without frontmatter, malformed frontmatter delimiters so the parser returns an empty object, or trimming the file and losing the header.

Related errors

• Invalid agent file frontmatter: ${errorDetails}
• Error parsing markdown frontmatter:
• Table name must be in format schema.table_name, got ${tableN
• Only rule files can be deleted
• FindAndReplaceMissingOldString

AI-assisted analysis of continuedev/continue@5522c6f44c (2026-08-27). Data as JSON: /api/errors/df0ddfaf2f40c516. Report an issue: GitHub.