Skill description field serves dual purpose (agent triggering + CLI picker display)

Resolved 💬 3 comments Opened Feb 26, 2026 by ddaanet Closed Mar 3, 2026

Problem

The description field in SKILL.md frontmatter serves two incompatible purposes:

  1. Agent triggering — Claude uses it to decide when to load a skill. The recommended format is "This skill should be used when the user asks to 'create X', 'configure Y'..." with specific trigger phrases.
  2. CLI picker display — The same text appears in the / slash command autocomplete menu as the user-facing description.

These have conflicting requirements. Good trigger text ("This skill should be used when...") is poor UX in a picker. Good picker text ("Create git commits") lacks the trigger phrases Claude needs.

Current behavior

❯ /
  /commit     Create git commits for completed work with short, dense, structured messages…
  /handoff    This skill should be used when the user requests a handoff, session update,…
  /design     This skill should be used when the user invokes /design, requests architect…
  /runbook    This skill should be used when the user invokes /runbook or needs a design d…

/commit reads well because its description happens to lead with an action verb. The others display the agent-targeted triggering language, which is unhelpful to users scanning the picker.

Why this can't be worked around

  • Custom frontmatter fields are stripped (#13005) — adding a custom field has no effect
  • H1 title is body content — not used in the picker display
  • Fallback (first paragraph) only activates when description is omitted entirely, which breaks agent triggering
  • Restructuring descriptions to lead with user-friendly text degrades trigger matching quality

Proposed solution

Add a display (or picker-text) frontmatter field for the user-facing text shown in the CLI picker. The existing description field continues to serve its current role as the agent-targeted triggering text.

---
name: handoff
display: Save session state for the next agent
description: This skill should be used when the user requests a handoff, session update, or agent switch.
---

Picker would show: /handoff Save session state for the next agent

If display is absent, fall back to current behavior (show description).

Environment

  • Claude Code on macOS
  • Multiple custom skills via .claude/skills/ and plugins

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗