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

${filePath} is missing a non-empty frontmatter "description"

Error message

${filePath} is missing a non-empty frontmatter "description"

What it means

Skill frontmatter validation error: the required `description` field is missing or empty. Every skill must declare a description so the agent can discover and select it.

Source

Thrown at src/cli/setup.ts:2286

		if (!match) {
			throw new Error(
				`${filePath} has invalid YAML frontmatter on line ${index + 2}: ${trimmed}`,
			);
		}

		const [, key, rawValue] = match;
		if (!rawValue.trim()) continue;

		const parsedValue = parseSkillFrontmatterScalar(rawValue, key, filePath);
		if (key === "name") name = parsedValue;
		if (key === "description") description = parsedValue;
	}

	if (!name) {
		throw new Error(`${filePath} is missing a non-empty frontmatter "name"`);
	}
	if (!description) {
		throw new Error(
			`${filePath} is missing a non-empty frontmatter "description"`,
		);
	}

	return { name, description };
}

export async function validateSkillFile(skillMdPath: string): Promise<void> {
	const content = await readFile(skillMdPath, "utf-8");
	parseSkillFrontmatter(content, skillMdPath);
}

const INSTALLED_SKILL_BADGE_PREFIX = "[OMX] ";

/**
 * Does this installed skill directory carry the badge OMX writes on install?
 *
 * The badge replaced a hand-maintained name list as the SIGNAL that a directory came from OMX, and it

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Add a non-empty `description:` line to the skill's frontmatter
2. Check for a description value that is only whitespace or an empty quoted string
3. Regenerate the skill file from a complete template if using a generator

Example fix

# before
---
name: code-linter
---

# after
---
name: code-linter
description: Lints code and reports issues
---

function hasSkillDescription(src: string): boolean {
  const m = src.match(/^---\r?\n([\s\S]*?)\r?\n---/);
  if (!m) return false;
  return /^description:\s*\S+.*$/m.test(m[1]);
}

When it happens

Trigger: Loading a skill file whose frontmatter has a `name` but no `description` key, or a blank/whitespace description value.

Common situations: Authors write the name and forget the description; automated generators emit partial headers; empty description string from templating placeholders.

Related errors

• ${filePath} frontmatter "${key}" must not be empty
• ${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} 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/f817ae2f6f5a4dbb. Report an issue: GitHub.