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

${filePath} frontmatter "${key}" must be a single-line strin

Error message

${filePath} frontmatter "${key}" must be a single-line string

What it means

The frontmatter parser only supports single-line scalars; a value of exactly '|' or '>' (YAML block scalar indicators) is rejected because multi-line block scalars are not supported for name/description.

Source

Thrown at src/cli/setup.ts:2218

	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`);
		}
		return unquoted;
	}

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Rewrite the value as a single-line quoted string
2. If it must be long, keep it on one line with quotes: description: "long text..."
3. Trim descriptions to a concise one-liner per skill conventions

Example fix

# before
---
name: s
description: |
  Long multi-line
  description
---
# after
---
name: s
description: "Long multi-line description condensed to one line"
---

const usesBlockScalar = /^[^:]+:\s*[|>]\s*$/m.test(frontmatterText);
if (usesBlockScalar) throw new Error("block scalars not supported in SKILL.md frontmatter");

try { parseSkillFrontmatter(content); } catch (e) { if (e instanceof Error && e.message.includes("single-line string")) { /* rewrite block scalar as one-line quoted value */ } else throw e; }

When it happens

Trigger: A frontmatter line such as 'description: |' or 'description: >' intending a folded/literal multi-line block.

Common situations: Authors copying multi-line YAML from other tools (CLAUDE.md, README generators) into SKILL.md; long descriptions written as blocks.

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 not be empty
• ${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/6e23e8654bf344d7. Report an issue: GitHub.