[FEATURE] Add `title` field to Skills for separate UI display vs AI description
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
Currently, Skills in Claude Code have only ONE description field that serves two conflicting purposes:
- For Claude (AI): Should be detailed with keywords to enable proper skill discovery and auto-triggering
- For REPL display: Should be short and concise to avoid cluttering the command menu
This forces a trade-off: either write short descriptions (poor AI discovery) or long descriptions (cluttered REPL interface).
Example of the problem:
When listing available skills with /help or autocomplete, users see walls of text like:
/my-skill - Extract text and tables from PDF files, fill PDF forms, merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, document extraction, or needs to combine files.
Instead of a clean:
/my-skill - PDF processing tools
Proposed Solution
Add an optional title field to SKILL.md frontmatter, following the same pattern already established in MCP Tools specification:
---
name: pdf-processing
title: PDF processing tools
description: Extract text and tables from PDF files, fill PDF forms, merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, document extraction.
---
MCP Tools already have this pattern:
| Field | Purpose | Audience |
|-------|---------|----------|
| name | Machine identifier | System |
| title | Human-readable display | UI/Users |
| description | Full explanation | AI model |
Reference: MCP Tools Specification
Behavior:
- If
titleis present → showtitlein REPL/autocomplete menus - If
titleis absent → fall back todescription(current behavior, backward compatible) - Claude always uses
descriptionfor skill discovery (unchanged)
Alternatives / Current Workarounds
- Write short descriptions - Results in poor AI discovery because Claude can't find the skill based on user intent
- Set
user-invocable: false- Hides skill from menu entirely, but then users can't manually invoke it - Accept cluttered REPL - Poor developer experience when managing many skills
None of these are satisfactory solutions.
Additional Context
- This aligns with existing MCP protocol conventions
- Backward compatible (title is optional)
- Minimal implementation effort (display logic change only)
- Benefits teams/users with many custom skills
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗