Feature: Add short-description field for skills display
Resolved 💬 2 comments Opened Feb 5, 2026 by kesly Closed Mar 6, 2026
Problem
When using / to invoke skills, the full description field is displayed in the terminal. For skills with detailed descriptions (which are useful for Claude to understand when to use them), this creates visual clutter and pollutes the terminal.
Current Behavior
The description field serves two purposes:
- Display: Shown to users when browsing skills with
/ - AI Context: Helps Claude understand when to automatically invoke the skill
These two purposes have conflicting requirements:
- Display needs to be short and scannable
- AI context benefits from being detailed with keywords and use cases
Proposed Solution
Add an optional short-description (or display-description) field in the YAML frontmatter:
---
name: my-skill
short-description: Clean up merged git branches
description: |
Clean up local git branches whose PRs have been merged.
Use when you want to remove stale branches, clean up after merges,
or maintain a tidy local git repository. Keywords: prune, delete, cleanup.
---
Behavior:
- If
short-descriptionexists → display it in the/menu - If not → fall back to
description(current behavior) - Claude always uses the full
descriptionfor context
Benefits
- Cleaner terminal UI when browsing skills
- No compromise on AI context quality
- Backward compatible (optional field)
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗