YAML frontmatter descriptions break in a specific way when wrapped to multiple lines: the parser either throws a syntax error (loud failure) or silently truncates the description to the first line (quiet failure). In the quiet failure case, your Claude Code skill appears to have a description. It does not. The AEM production bar requires a valid single-line description or a correctly declared YAML block scalar. The metadata layer shows a partial string, the trigger mechanism receives an incomplete signal, and the skill either never activates or activates inconsistently, with no error message explaining why.

TL;DR: A SKILL.md description must be a single-line string or a valid YAML block scalar. When a description wraps to a second line without correct block scalar syntax, the parser silently discards everything after the first line break. Prettier causes this by reflowing text without checking YAML validity. The symptom requires direct YAML inspection to distinguish from a badly written description.

Why does a multi-line YAML description break skill discovery?

The description field in SKILL.md frontmatter is a YAML scalar: a single value assigned to a key. A multi-line description breaks skill discovery because Claude Code's YAML parser either rejects the file entirely or silently reads only the first line, leaving the trigger classifier with an incomplete signal that cannot match full-context prompts reliably. When you write:

description: "This skill analyzes incoming customer support tickets for sentiment
and routes them to the appropriate team based on priority score."

The YAML parser sees a quoted string that opens on line 1 and a second line that starts without the closing quote on line 1. Depending on which YAML parser the platform uses, this either throws a parse error (skill not loaded at all) or silently terminates the string at the first line break and discards "and routes them to the appropriate team based on priority score."

Both break skill discovery. In the silent truncation case, the description becomes "This skill analyzes incoming customer support tickets for sentiment." It matches some inputs but misses the routing context entirely. The skill activates on the wrong prompts and ignores the prompts it was designed for. A 650-trial study of skill activation rates found that description quality alone creates a 20.6x difference in activation odds between poorly and correctly specified descriptions (Ivan Seleznov, Medium, 2024). A truncated description puts you at the bottom of that range by default.

"The failure mode isn't that the model is bad at the task — it's that the task wasn't specified tightly enough. Almost every production failure traces back to an ambiguous instruction." — Simon Willison, creator of Datasette and llm CLI (2024)

A truncated description is an ambiguous instruction, produced silently by a formatting tool. Claude Code's skill authoring best practices documentation states that the description "must provide enough detail for Claude to know when to select this Skill" from a pool of potentially 100 or more available skills (Anthropic, platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).

What are the three specific YAML failure modes?

Three distinct failure modes break SKILL.md descriptions in Claude Code skills: a quoted string with an embedded line break, an unquoted string with an apparent continuation, and a description exceeding the 1,024-character field limit (Anthropic, platform.claude.com). All three produce the same symptom: a skill that triggers inconsistently or not at all, with no error message identifying the cause.

  1. Failure Mode 1: Quoted string with an embedded line break. The closing quote sits on a different line from the opening. In strict YAML, this is a syntax error. Some parsers handle it using flow scalar rules and collapse the lines; others fail. The behavior is parser-dependent and not something to rely on.
description: "First line of description
second line of description"
  1. Failure Mode 2: Unquoted string with apparent line continuation. The most common silent failure pattern. The YAML parser reads line 2 as a new mapping entry, not a continuation. The description becomes "First line of description" only. "second line of description" is either discarded or causes a parse error. A confirmed real-world audit found approximately 16% of workspace skills affected by YAML parse issues of this type, with no actionable error surfaced to the user (GitHub openclaw/openclaw issue #22134, 2024).
description: First line of description
  second line of description
  1. Failure Mode 3: Description exceeds the 1,024-character limit. If the description is valid YAML but exceeds 1,024 characters, Claude Code truncates it at the limit. The first 1,024 characters remain, the rest is dropped. This is a documented constraint, not a silent failure, but it produces an identical symptom: description seems truncated, skill triggers inconsistently. Note that Claude Code 2.1.86 introduced an additional 250-character cap on descriptions shown in the /skills listing to reduce context usage; only the first 250 characters appear there regardless of total description length (Anthropic, GitHub issue #40121, 2024).

How does Prettier or auto-formatting cause this?

Prettier's YAML formatter reflows strings based on a configured printWidth without checking whether the reflow produces valid YAML. The default printWidth in most projects is 80 characters. A SKILL.md description that is 120 characters long gets reflowed to two lines of 80 characters each, introducing a line break that breaks the description scalar.

The resulting file looks correct in a text editor with word wrap. The description appears intact. The YAML structure is broken.

This is the most common silent failure in community-distributed skills. The original author writes a valid single-line description. A contributor runs Prettier as part of a pre-commit hook. The description splits. The skill stops triggering. The contributor does not notice because the visual appearance of the file is unchanged. Prettier logs 81 million weekly downloads on npm as of April 2026 (npmjs.com, 2026), which maps directly to how many JavaScript and TypeScript projects have a pre-commit hook capable of silently corrupting SKILL.md frontmatter.

In our AEM skill library audits, Prettier-caused description truncation accounts for the majority of description formatting failures we see in skills submitted for the production bar check. The description looks intact in the editor. The YAML is broken. The skill fails silently on natural-language prompts while responding normally to explicit /skill-name invocations, which is exactly the diagnostic gap that makes this failure hard to locate without reading raw YAML.

Prettier's own issue tracker confirms the problem. GitHub issue #16443 documents that "incorrect YAML formatting produces invalid YAML" as a confirmed bug in Prettier's YAML handling, filed against Prettier 3.x (Prettier project, GitHub, 2024). The proseWrap: preserve override is the recommended workaround.

The fix has two parts:

  1. Keep descriptions on a single line in YAML frontmatter
  2. Add a Prettier override for SKILL.md files:
{
  "overrides": [
    {
      "files": ["SKILL.md"],
      "options": { "proseWrap": "preserve" }
    }
  ]
}

This prevents Prettier from reflowing frontmatter strings in skill files.

How do you detect and fix a broken description?

Detection takes two grep commands run against the SKILL.md file directly: one checks whether the description value ends on the same line as the key, confirming no line break failure; the second checks character count against the 1,024-character field limit. Both checks together cover all three failure modes and complete in under five seconds.

Detection:

Check whether the description value ends on the same line as the key:

grep -n "description:" SKILL.md

If the description value does not end on the same line as description:, it is formatted incorrectly. For teams running CI pipelines, yamllint automates this check across all SKILL.md files in a repository; the package logs 28.7 million downloads per month on PyPI as of April 2026 (pypistats.org, 2026), indicating how broadly YAML validation tooling is adopted for exactly this class of problem.

Check character count against the 1,024-character limit:

awk '/^description:/{print length($0)}' SKILL.md

Fix Option 1 (preferred): Single line with quotes.

description: "This skill analyzes incoming customer support tickets for sentiment and routes them to the appropriate team based on priority score."

Fix Option 2: YAML folded block scalar.

description: >
  This skill analyzes incoming customer support tickets for sentiment
  and routes them to the appropriate team based on priority score.

The > tells YAML to collapse line breaks into spaces. The resulting parsed value is a single-line string. Safe for descriptions that genuinely need 200+ characters to remain readable in source. The YAML spec (version 1.2.2, yaml.org) defines the folded block scalar as the correct mechanism for multi-line source representation of single-line values; it is parser-agnostic and does not rely on implementation-specific behavior.

Both options produce a single-value string that the skill discovery mechanism reads correctly.

The single-line and > block scalar fixes address formatting failures only. They do not prevent truncation if the description exceeds 1,024 characters, and they do not address the 250-character display cap introduced in Claude Code 2.1.86 for the /skills listing. A description that is correctly formatted but too long will still be truncated at display time; front-load your trigger phrases to stay within the visible window.

For diagnosing why a skill with a correctly formatted description still fails to trigger, see My Skill Produces Great Output but Never Activates Automatically — the description content rather than the formatting may be the issue.

FAQ

A correctly formatted description is the prerequisite for skill discovery. When formatting fails silently, the skill appears installed, runs on explicit invocation, and produces no error. The trigger classifier receives an incomplete signal and the skill never auto-activates on natural language prompts. Fix formatting before optimizing trigger phrases.

What does a silent truncation failure look like from the user's perspective?

The skill is installed, runs when explicitly invoked with /skill-name, but never auto-triggers on natural language prompts. Or it triggers inconsistently — on some phrasings but not others. This symptom is identical to a description that is poorly written but correctly formatted. The only way to distinguish them is to check the YAML structure directly.

How do I know if my description is being truncated at 1,024 characters?

Count the characters in your description value (not including the description: key and quotes). If it is over 1,024 characters, it is truncated. Rewrite to fit — prioritize the trigger language and any exclusion statements. The tail of the description, usually additional context, is what gets cut.

Does the folded block scalar fix work across all Claude Code versions?

The folded block scalar (>) is valid YAML and parses correctly across versions. The literal block scalar (|) preserves line breaks within the string, producing multi-line content in the parsed value — not appropriate for descriptions, which should parse as single-line strings. Use > for multiline source formatting.

Can I test YAML validity without running a full Claude Code session?

Yes. Any YAML linter validates frontmatter structure. Command-line tools like yq parse the frontmatter and report errors. Online YAML validators work equally well. This is faster than a full Claude Code test cycle for format-only issues. The yq Python package alone logs 3.3 million monthly downloads on PyPI as of 2026 (pypistats.org, 2026), which reflects how broadly YAML tooling is embedded in developer workflows outside the Node.js ecosystem.

Is this a Claude Code bug or expected YAML behavior?

Expected YAML behavior. The YAML specification defines how multi-line scalars work. Claude Code's frontmatter parser follows the YAML spec. This is a formatting discipline issue for skill authors, not a platform bug. That said, YAML parsing inconsistency in Claude Code's broader frontmatter layer is a confirmed platform issue: GitHub issue #13905 (anthropics/claude-code, filed December 2025, labeled "bug") documents invalid YAML syntax in the official .claude/rules/ documentation breaking CI/CD pipelines, confirming that the platform's YAML handling is non-trivial even outside skill descriptions.

How does this connect to trigger-phrase writing for skill discovery?

A correctly formatted description is the prerequisite. If the formatting is wrong, trigger-phrase optimization is wasted effort — the classifier never sees the trigger phrases because the description is truncated or invalid. Fix the formatting first. Then see How Do I Write Trigger Phrases That Make My Skill Activate Reliably? for content-level improvements.

Last updated: 2026-04-19