claude-code - 💡(How to fix) Fix Skill descriptions silently dropped from system reminder for ~half of a plugin's skills

Summary

In a fresh session, the available-skills list injected at session start renders some skills with their full description and others as just a bare - skill-name line — no description at all. The descriptions are present and valid in the SKILL.md files on disk; something between disk and the system reminder is dropping them.

In my session, 19 skills lost their descriptions: 18 of 40 from the marketing-skills plugin (v1.9.0) plus the built-in init. The other 22 marketing-skills entries rendered correctly.

User reports this was working fine until now — points to a recent regression.

Environment

• Claude Code 2.1.137
• Harness: cmux (/Applications/cmux.app/Contents/Resources/bin/claude)
• Plugin: marketing-skills@marketingskills v1.9.0 (installedAt 2026-03-05, lastUpdated 2026-05-04, cache dir refreshed locally 2026-05-08)
• macOS Darwin 25.3.0

Diagnostics performed

1. YAML validity — Ruby YAML.safe_load on every SKILL.md frontmatter under ~/.claude/plugins/cache/marketingskills/marketing-skills/1.9.0/skills/: all 40 parse cleanly, every description field populated (461–824 chars).
2. Content drift — popup-cro/SKILL.md is byte-identical between the active 1.9.0/ cache and an older 2f5db8d95cff/ hash cache that coexists in the same plugin directory. Same bytes, but only one set of descriptions makes it through.
3. Pattern hunt for what gets dropped:
   • Length: not it. directory-submissions (824 chars) renders fine; popup-cro (538) doesn't.
   • Em dashes / smart quotes: mixed on both sides — not the discriminator.
   • Frontmatter structure: identical between dropped and preserved skills (same name / description / metadata.version shape).
   • Leading-quote vs unquoted YAML scalar: mixed on both sides.
4. Two coexisting cache directories for the same plugin:
   • ~/.claude/plugins/cache/marketingskills/marketing-skills/1.9.0/ (active per installed_plugins.json)
   • ~/.claude/plugins/cache/marketingskills/marketing-skills/2f5db8d95cff/ (older, slightly fewer skills)
   • Wondering if dedup/loading across both caches is implicated.

The 19 skills that lost their descriptions

From marketing-skills: popup-cro, competitor-alternatives, pricing-strategy, seo-audit, cold-email, ai-seo, social-content, video, sales-enablement, customer-research, lead-magnets, site-architecture, form-cro, ad-creative, programmatic-seo, signup-flow-cro, ab-test-setup, free-tool-strategy

Built-in: init

What rendering looks like in the system reminder

Working entry (kept):

- marketing-skills:email-sequence: When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. ...

Broken entry (dropped):

- marketing-skills:popup-cro

Impact

Skills still invoke correctly when called by name, but Claude is much less likely to proactively suggest skills whose descriptions it can't see at session start — defeating a core mechanism of plugin discovery.

Repro

1. Install marketing-skills plugin v1.9.0
2. Start a fresh session
3. Inspect the available-skills list in the system reminder; observe ~18 marketing-skills entries with no description while ~22 render fully

Happy to provide additional diagnostics — installed_plugins.json excerpts, full lists, etc. — on request.