Skill description field serves dual purpose (agent triggering + CLI picker display)
Problem
The description field in SKILL.md frontmatter serves two incompatible purposes:
- 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. - 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
descriptionis 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
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗