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:

  1. Display: Shown to users when browsing skills with /
  2. 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-description exists → display it in the / menu
  • If not → fall back to description (current behavior)
  • Claude always uses the full description for context

Benefits

  • Cleaner terminal UI when browsing skills
  • No compromise on AI context quality
  • Backward compatible (optional field)

View original on GitHub ↗

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