### Preflight Checklist - [x] I have searched [existing issues](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug) and this hasn't been reported yet - [x] This is a single bug report (please file separate reports for different bugs) - [x] I am using the latest version of Claude Code ### What's Wrong? When creating skills with long descriptions, code formatters like Prettier automatically wrap YAML frontmatter descriptions across multiple lines without

IMHO, this is not a duplicate of the flagged issues: - #10589 describes the opposite problem (Skills with `|` not working). In my case, the `|` operator works correctly as a workaround. - #4700 and #7943 describe the same Prettier issue but for Agents, not Skills. These are separate features that may have separate implementations. - My issue is the first to report the Prettier formatting problem specifically affecting Skills. While the root cause may be the same YAML parser across Skills and A

[BUG] Skill frontmatter parser fails on Prettier-formatted multi-line descriptions

Status Closed — not planned

Maintainer reply None cached

Workaround ✓ Mentioned in thread ↓

Activity 8 comments · opened Nov 9, 2025 · closed Feb 10, 2026

Preflight Checklist

[x] I have searched existing issues and this hasn't been reported yet
[x] This is a single bug report (please file separate reports for different bugs)
[x] I am using the latest version of Claude Code

What's Wrong?

When creating skills with long descriptions, code formatters like Prettier automatically wrap YAML frontmatter descriptions across multiple lines without adding YAML multi-line operators (| or >). This causes Claude Code to fail parsing the skill frontmatter, making the skill undiscoverable.

In projects with pre-commit hooks that enforce Prettier formatting, skills become invisible to Claude after the formatter runs.

What Should Happen?

Claude Code should parse multi-line YAML descriptions even without explicit operators.

Error Messages/Logs

No explicit error is shown. The skill simply doesn't appear when asking "What skills do you have?" in a new Claude session.

Steps to Reproduce

Create a skill file .claude/skills/example-skill/SKILL.md:

---
name: example-skill
description: This is a very long description that exceeds typical line length limits and will be automatically wrapped by code formatters like Prettier when configured with line length restrictions commonly used in projects.
---

# Example Skill
Instructions here...

Start a new Claude Code session
Ask "_What skills do you have?_" ⭢ The skill IS listed and discoverable
Run Prettier on the file (with line length limit configured, e.g., 120 characters)
Prettier reformats the frontmatter to:

---
name: example-skill
description:
  This is a very long description that exceeds typical line length limits and will be
  automatically wrapped by code formatters like Prettier when configured with line length
  restrictions commonly used in corporate projects.
---

# Example Skill
Instructions here...

Start a new Claude Code session
Ask "_What skills do you have?_" ⭢ The skill is NOT listed
Manually fix by adding | operator:

---
name: example-skill
description: |
  This is a very long description that exceeds typical line length limits and will be
  automatically wrapped by code formatters like Prettier when configured with line length
  restrictions commonly used in corporate projects.
---

# Example Skill
Instructions here...

Start a new Claude Code session
Ask "_What skills do you have?_" ⭢ The skill IS listed back again

Claude Model

Sonnet (default)

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.0.8 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

iTerm2

Additional Information

_No response_

View original on GitHub ↗

8 Comments

github-actions[bot] · 11 months ago

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

sesyilmaz · 11 months ago

IMHO, this is not a duplicate of the flagged issues:

#10589 describes the opposite problem (Skills with | not working). In my case, the | operator works correctly as a workaround.
#4700 and #7943 describe the same Prettier issue but for Agents, not Skills. These are separate features that may have separate implementations.
My issue is the first to report the Prettier formatting problem specifically affecting Skills.

While the root cause may be the same YAML parser across Skills and Agents, this requires a parser fix rather than just documentation. As documentation alone won't prevent the silent failures that might occur when code formatters run automatically.

Additional context from related issues:

Issue #10504 proposes documenting and standardizing the | syntax for multi-line descriptions. However, as noted in its comments, this solution is defeated if multi-line descriptions without | are ignored (which is what my issue and #4700/#7943 report). Even if we
follow documentation to use |, Prettier may strip it on commit unless properly configured.

The core problem: In most organizations, code formatters like Prettier are enforced via pre-commit hooks or CI/CD pipelines. This creates a problematic workflow:

Developer creates a skill with a long single-line description → ✓ Works
Developer tests locally → ✓ Skill is discoverable
Developer commits → Pre-commit hook runs Prettier automatically
Prettier reformats the YAML without | operator → ✗ Skill silently breaks
The skill appears to work locally (before commit) but fails after commit

PaulRBerg · 10 months ago

yeah, it's a duplicate issue

github-actions[bot] · 9 months ago

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

PaulRBerg · 9 months ago

please keep active, it's annoying issue that persists

github-actions[bot] · 8 months ago

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

marcindulak · 8 months ago

This issue was closed incorrectly despite recent human comments. This behavior of the bot is reported at https://github.com/anthropics/claude-code/issues/16497. Please upvote that issue, so maybe it gets noticed.

github-actions[bot] · 7 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.