Yeachan-Heo/oh-my-codex · error · Error

${filePath} frontmatter "${key}" must not be empty

Error message

${filePath} frontmatter "${key}" must not be empty

What it means

When parsing SKILL.md YAML frontmatter, a scalar value that trims to an empty string is rejected. This variant fires for the top-level trim: the raw frontmatter value contained only whitespace (or was empty after the colon).

Source

Thrown at src/cli/setup.ts:2215

		readFile(src, "utf-8"),
		readFile(dst, "utf-8"),
	]);
	return srcContent !== dstContent;
}

function containsTomlKey(content: string, key: string): boolean {
	const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
	return new RegExp(`^\\s*${escapedKey}\\s*=`, "m").test(content);
}

function parseSkillFrontmatterScalar(
	value: string,
	key: string,
	filePath: string,
): string {
	const trimmed = value.trim();
	if (!trimmed) {
		throw new Error(`${filePath} frontmatter "${key}" must not be empty`);
	}
	if (trimmed === "|" || trimmed === ">") {
		throw new Error(
			`${filePath} frontmatter "${key}" must be a single-line string`,
		);
	}

	const quote = trimmed[0];
	if (quote === '"' || quote === "'") {
		if (trimmed.length < 2 || trimmed.at(-1) !== quote) {
			throw new Error(
				`${filePath} frontmatter "${key}" has an unterminated quoted string`,
			);
		}
		const unquoted = trimmed.slice(1, -1).trim();
		if (!unquoted) {
			throw new Error(`${filePath} frontmatter "${key}" must not be empty`);
		}

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Open the SKILL.md named in the message and fill in a non-empty value for the flagged key
2. Use a YAML linter or the library's parseSkillFrontmatter in CI to catch this early
3. Keep name and description on one line: 'name: my-skill'

Example fix

# before
---
name:
description: does things
---
# after
---
name: my-skill
description: does things
---

const fm = parseSkillFrontmatter(content, "SKILL.md"); // throws early with a precise message
const hasValue = (v?: string) => !!v && v.trim().length > 0;
if (!hasValue(fm.name) || !hasValue(fm.description)) throw new Error("empty frontmatter field");

const nonEmpty = (v: string | undefined): v is string =>
  typeof v === "string" && v.trim().length > 0;

try { parseSkillFrontmatter(content); } catch (e) { if (e instanceof Error && e.message.includes("must not be empty")) { /* highlight the flagged key in the editor */ } else throw e; }

When it happens

Trigger: A frontmatter line like 'name:' or 'description: ' where the value side contains nothing but whitespace.

Common situations: Hand-authored SKILL.md files with a forgotten value, template placeholders deleted, or copy-paste leaving empty keys.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• ${filePath} frontmatter "${key}" must be a single-line strin
• ${filePath} frontmatter "${key}" has an unterminated quoted
• ${filePath} is missing a non-empty frontmatter "name"
• ${filePath} is missing a non-empty frontmatter "description"
• ${filePath} must start with YAML frontmatter containing non-

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/f7174a60dc1a4789. Report an issue: GitHub.