Feature Request: Add description metadata to custom slash commands

Feature Request: Add description metadata to custom slash commands

Environment

• Platform: Anthropic API
• Claude CLI version: 1.0.5
• Operating System: macOS 15.0
• Terminal: Terminal.app

Feature Description

Currently, all custom slash commands appear as "Custom command" in the command dropdown menu, making it difficult to distinguish between different commands. This impacts discoverability and usability when projects have many custom commands.

Problem

• All custom commands show identical "Custom command" text in dropdown
• No way to provide descriptions or tooltips for commands
• Users must memorize command names without visual hints
• Poor UX compared to built-in commands which have descriptions

Proposed Solution

Allow command files to include metadata that would be displayed in the dropdown:

Option 1: YAML frontmatter in command files

---
description: "Stop FlowLoom session and clean up isolation"
category: "Session Management"
icon: "🛑"  # optional
---

# Command content...

Option 2: First line convention

# @description Stop FlowLoom session and clean up isolation

# Rest of command...

Option 3: Separate metadata file

.claude/commands/metadata.json:

{
  "flowloom/session/stop": {
    "description": "Stop FlowLoom session and clean up isolation",
    "category": "Session Management"
  }
}

Expected Behavior

• Custom commands would show their descriptions in the dropdown
• Better discoverability of command functionality
• Consistent UX with built-in commands

Impact

This would significantly improve the user experience for projects with extensive custom command libraries, making Claude Code more powerful for advanced workflows.

Related Issues

• None found specifically requesting this feature

Additional Context

Projects like FlowLoom have 50+ custom commands, and the current "Custom command" display makes it challenging for users to discover and use the right commands efficiently.