Two plugin skills listed without their frontmatter descriptions in the system-prompt skill list

Open 💬 0 comments Opened Jul 6, 2026 by avegancafe

Environment

Claude Code 2.1.201, macOS (darwin 25.4), marketplace plugin installed from a GitHub-source marketplace with autoUpdate.

Bug

In a plugin with ~43 skills, exactly two are surfaced in the session system prompt's available-skills list without their descriptions (bare - plugin:skill-name lines), while all sibling skills in the same plugin render - plugin:skill-name: <description>. A skill listed without its description can never trigger by description matching, which silently defeats it.

What I verified

  • Both skills' SKILL.md frontmatter is valid YAML with name: matching the directory and a normal one-paragraph description: — verified with pyyaml.
  • The description is present and identical in the source repo, in the marketplace copy under ~/.claude/plugins/marketplaces/<mp>/, and in every cached version under ~/.claude/plugins/cache/<mp>/<plugin>/<ver>/ (1.22.0 → 1.30.0).
  • The repo's CI validates SKILL.md frontmatter as real YAML; both files pass.
  • Restart/reload does not change the behavior; the same two skills are affected across sessions and across plugin versions.

Example frontmatter of one affected skill:

---
name: updating-cloudsql-flags
description: Use when setting, adding, removing, or changing database flags on a Cloud SQL Postgres instance — via `gcloud sql instances patch --database-flags`, the Cloud SQL Admin API (`settings.databaseFlags`), or the GCP console.
---

The second affected skill's description similarly contains an em dash, backticks/URL-ish tokens, and a --flag string — but so do several sibling skills that render fine, so we could not find the distinguishing property.

Expected

Every skill with a valid frontmatter description appears in the skill list with that description.

Question

What causes a skill's description to be dropped at listing time? If there's a parse/sanitization step that can reject a description silently, a warning (e.g. in claude doctor or the plugin validation path) would make this debuggable.

View original on GitHub ↗