Feature request: per-skill display description separate from the routing description (SKILL.md)

Status Open
Maintainer reply None cached
Activity 0 comments · opened Aug 19, 2026

Problem

A skill's SKILL.md frontmatter description currently serves two consumers with opposing needs:

  1. Model routing — Claude reads the full description to decide when to invoke the skill. Rich descriptions (concrete trigger phrases, "do NOT use for…" exclusions) measurably improve trigger accuracy, so well-governed catalogs write long ones (~800–1000 chars).
  2. UI display — the claude.ai / picker tooltip and plugin detail pages render the same string. The tooltip shows ~400+ characters before truncating, so a routing-optimized description renders as a wall of text.

There is no way to improve one without degrading the other: shortening the description shrinks the tooltip but strips the trigger phrases and exclusions the routing depends on; keeping it long makes the hover unreadable. Front-loading a summary sentence helps the first impression but does not reduce the tooltip's size.

Context

We run an organization plugin marketplace (governed catalog, ~16 skills across 3 plugins, synced to claude.ai via the org marketplace). Our validation pipeline benchmarks descriptions for trigger accuracy (positive/negative prompt sets), which pushes descriptions toward rich trigger text — exactly the text that overwhelms the hover UI. This tension will hit any org catalog that takes skill-triggering seriously.

Requested

An optional per-skill display field in SKILL.md frontmatter — e.g. displayDescription (or summary) — used by UI surfaces (picker tooltip, plugin detail pages, hover), falling back to description when omitted. Routing/invocation continues to read description unchanged.

Precedent already exists at the plugin level: displayName in plugin.json / marketplace.json is exactly this pattern ("shown in UI surfaces… not used for namespacing or lookup"). This request is the same separation, one level down.

Alternative

If a new field isn't desirable: sentence-aware tooltip truncation (cut at the first sentence boundary past ~150 chars) would capture most of the benefit with no schema change.

View original on GitHub ↗