anthropics / anthropics/claude-code
[BUG] Unindented multi-line frontmatter description silently fails to parse, falls back to first body heading
- Dominant language
- Python
- Stars
- 145k
- Forks
- 23.1k
- PR merge metrics
- PR metrics pending
Description
### Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet (as this exact repro/symptom — see Related below for adjacent reports)
- [x] This is a single bug report
- [x] I am using the latest version of Claude Code
### What's Wrong?
A command/skill frontmatter `description:` written as a YAML plain scalar that wraps onto multiple lines *without indenting the continuation lines* (i.e. the continuation starts at column 0, same as the `description:` key itself) silently fails to parse. The skill/command still loads and is invokable, but the description used in the "available skills" listing (and presumably `/help`) falls back to the first `##` heading in the markdown body instead — with no warning anywhere.
This is dangerous specifically because the fallback text can look plausible (a real heading, not an error message), so nothing signals that the actual trigger description was lost. In my case, a command written to be proactively auto-invoked for SSH/remote work ended up listed as just "Available Tools" — a bare section heading — giving the model zero signal to ever choose it. It had 0 recorded invocations across ~200 sessions before I found the cause.
### What Should Happen?
Either: (a) the parser should accept this form (it's valid YAML — a plain scalar folds newlines to spaces regardless of the continuation's indentation relative to the key, as long as it's more indented than the parent mapping), or (b) if it's intentionally rejected, Claude Code should surface a warning (e.g. via `claude plugin validate`, or on load) instead of silently substituting fallback text.
### Steps to Reproduce
1. Create `~/.claude/commands/repro.md`:
```yaml
---
name: repro
description: This is a description that wraps onto multiple lines
without indenting the continuation -- exactly what a formatter like
Prettier, or hand-wrapping at 80 columns, tends to produce.
---
## Some Heading
Body text.
```
2. Start Claude Code and look at the "available skills" listing (or `/help`).
3. Expected: the full description text. Actual: `repro: Some Heading`.
### Claude Code Version
2.1.270 (Claude Code)
### Is this a regression?
No, this never worked (reports of this pattern go back to at least Feb 2026 — see Related).
### Platform / OS / Terminal
Anthropic API / Ubuntu 24.04 (Linux) / kitty
### Additional Information
Related prior reports of the same underlying pattern, none of which landed a fix — each was closed by automation rather than resolved:
- #11322 — same trigger (Prettier-wrapped multi-line description), auto-closed after 60 days' inactivity despite active discussion at the time it closed
- #12313 — related (`|`/`>` block-scalar variant renders literally as `"| (user)"`), closed not-planned/duplicate
- #67131 — related (mid-line `...` variant), auto-closed as a duplicate of #61099, which is actually a different bug (Write/Edit tool rewriting memory-file frontmatter on save) — looks like a bot mismatch rather than a real resolution
Flagging this history so it isn't auto-closed the same way a fourth time.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the minimal ~/.claude/commands/repro.md frontmatter example and check the available-skills listing or /help. Trace the frontmatter loading path, then verify that the full description is preserved or that an explicit validation/load warning appears instead of the first body heading.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, yaml
- Domain
- cli, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100