Skill with unquoted ": " in SKILL.md description is silently dropped from the skills list / slash menu (CLI, no diagnostic)
Summary
A plugin skill whose SKILL.md frontmatter description: is an unquoted YAML plain scalar containing a colon-space (: ) fails strict YAML parsing (mapping values are not allowed here). When this happens, Claude Code silently omits the skill from the skills listing and the / slash-command menu in every session — with no warning, no error, and nothing in claude doctor or /skills to indicate a skill was dropped.
The Skill tool can still invoke the skill by its exact name (plugin:skill), which masks the problem: the author sees it "work" when called explicitly and reasonably concludes it's installed correctly, while users can't discover it and slash-invocation fails.
Why it's easy to hit
: is extremely common in natural-language descriptions (Use when: ..., Covers: X, Y, Z, Two modes: forward and backward). In YAML, an unquoted plain scalar containing : is parsed as an attempted mapping, which throws. Authors rarely quote descriptions, so this is a latent trap.
Minimal repro
- Create a plugin skill
skills/demo-skill/SKILL.md:
```markdown
---
name: demo-skill
description: Does a thing. Use when: you need the thing done.
---
# Demo Skill
Body here.
```
(The unquoted Use when: — specifically the : — is the trigger.)
- Install/enable the plugin and start a session (or
/reload-plugins). - Observed:
demo-skillis absent from/skillsand the/menu. ButSkill(name="<plugin>:demo-skill")invokes it fine. - Quote the description —
description: "Does a thing. Use when: you need the thing done."— reload, and the skill reappears in the listing/menu.
Verified deterministically: python -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1])" raises mapping values are not allowed here for the unquoted form and succeeds for the quoted form. In a real private marketplace this silently hid 6 skills (each had a : in an unquoted description) until they were quoted.
Expected behavior
At minimum, fail loud: when a SKILL.md is skipped because its frontmatter fails to parse, emit a warning that names the skill file and the parse error (at load / /reload-plugins time), and/or surface a "N skills failed to load" line in claude doctor and /skills. A silent drop with a working exact-name invocation path is the core problem — it makes the failure nearly undiagnosable without manually strict-parsing every frontmatter.
Optionally, a lenient-parse fallback for the description field (treat a plain scalar as a literal string up to the newline) would make the common colon-space case Just Work.
Environment
- Claude Code
2.1.211, Windows 11 - Plugin skills installed via a marketplace; skills are namespaced
plugin:skill
Related (possibly same umbrella, but distinct triggers)
- #77269 — claude.ai web Directory silently drops a skill whose description contains
<>/[]. Similar silent-drop symptom, but that's character sanitization on the web platform; this report is a strict-YAML structural failure (colon-space) in the CLI. - #74639 — plugin skills listed without their frontmatter descriptions. Possibly the same parse failure surfacing as degraded-listing rather than full drop.
- #68677 (closed) — skill descriptions not surfaced for ~50% of user-defined skills.
Happy to provide additional repros or test a fix.