[FEATURE] Add Skill Autocomplete to CLI (Parity with VS Code Extension)

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

TLDR

VS Code Extension v2.0.26 shows skills in / autocomplete. CLI v2.0.26 doesn't. Both environments support /skill-name commands when invoked directly. This is a parity request to make CLI match VS Code Extension behavior. The absence of this in CLI can lead to the user manually adding a slash command for a skill, which causes problems due to the collision.

Why this matters: Issue #9710 claimed "there's currently no autocomplete menu" for skills, but this is factually incorrect for VS Code Extension. We have evidence that skills appear in VS Code's / autocomplete. CLI should match this established behavior.

---

Related Issues & Critical Clarifications

Addressing Issue #9710

Issue #9710 stated: "there's currently no autocomplete menu for them [skills]"

However, this is factually incorrect for VS Code Extension v2.0.26. The VS Code Extension DOES show skills in autocomplete when typing /. We have screenshots and can demonstrate this behavior. Skills appear in the dropdown alongside built-in commands.

The maintainer suggested "adding a separate syntax for autocompleting skills" (implying non-/ syntax). We respectfully disagree with this approach because:

1. /skill-name syntax already exists and works - Both CLI and VS Code Extension support it when invoked directly
2. Users observe this syntax in action - When the agent invokes skills, users see the /skill-name command being used, establishing user expectation
3. Different syntax adds cognitive load - Users would need to remember / for commands and something else for skills (e.g., @skill-name or #skill-name)
4. Doesn't prevent collisions - Users can still manually create .claude/commands/skill-name.md files, causing the same collision issues
5. VS Code Extension sets precedent - Skills already appear under / autocomplete in VS Code, making it the established pattern

Distinct from Issue #9750

Issue #9750 is about general slash command autocomplete improvements (file paths, fuzzy search, etc.). Our request is skills-specific and addresses the inconsistency between CLI and VS Code Extension skill autocomplete. These are separate concerns and should not be treated as duplicates.

---

Summary

The VS Code Extension shows auto-generated /skill-name slash commands in autocomplete when users type /, but the CLI does not show these commands despite supporting them.

Since natural language invocation of skills is not always reliable (may or may not trigger the skill), users may prefer a deterministic way to invoke skills.
In both versions, there is an (apparently) undocumented auto-generated slash command for each skill, which will run the skill.
In VS Code, these auto-generated slash commands work with autocomplete. In CLI, the lack of autocomplete may cause users to create manual slash commands in .claude/commands/ as a workaround for discoverability, which then creates name collisions with the auto-generated skill commands in both environments.

Request: Add skill autocomplete to CLI matching the VS Code Extension behavior, providing consistent discoverability and eliminating the need for manual workaround commands.

---

Evidence: /skill-name Syntax Already Exists and Works

Proof #1: VS Code Extension Shows Skills in Autocomplete

Contrary to Issue #9710's claim, the VS Code Extension (v2.0.26) DOES show skills in autocomplete:

When typing / in VS Code Extension:

Autocomplete dropdown shows:
  /clear
  /context
  /glyph-add       ← From ~/.claude/skills/glyph-add/
  /glyph-list      ← From ~/.claude/skills/glyph-list/
  [... other commands and skills ...]

This is observable, reproducible behavior. Skills appear alongside built-in commands when typing /.

Proof #2: CLI Supports /skill-name Commands (Just Hidden)

The CLI also supports these commands when invoked directly:

User typed in CLI: /glyph-add

Output:
<command-message>The "glyph-add" skill is running</command-message>
<command-name>glyph-add</command-name>

🔍 GLYPH-ADD SKILL LOADED  ← Trap phrase from SKILL.md proves full skill loaded

Perfect! I can help you add a new glyph to the mystical inventory.
[... skill executes correctly ...]

The functionality exists - it just doesn't show in autocomplete.

Proof #3: Users Observe Agent Using /skill-name Syntax

When Claude invokes skills internally, the system shows:

Skill
IN
{
  "command": "glyph-add"
}

OUT
Launching skill: glyph-add
/glyph-add
[... skill content ...]

Users see /skill-name being used, creating the reasonable expectation that this is valid user-invocable syntax.

Conclusion from Evidence

1. VS Code Extension already implements this - Skills show in / autocomplete
2. CLI already supports it - /skill-name commands work when typed
3. Users observe this pattern - The agent demonstrates the syntax
4. Only missing: CLI autocomplete UI - Everything else exists

This isn't requesting new functionality - it's requesting UI parity between CLI and VS Code Extension for existing functionality.

---

Discovery Process: From Bug Report to Feature Request

Initial Problem (Appeared to be a Bug)

We initially thought this was a "slash command collision bug" in VS Code Extension because:

1. Manual slash commands in .claude/commands/ collided with skills in ~/.claude/skills/
2. The collision caused unpredictable behavior (sometimes full SKILL.md loaded, sometimes not)
3. We thought manual commands were necessary for CLI compatibility

Note: Detailed collision behavior analysis with real-world examples is available if needed for debugging purposes.

Discovery: VS Code Extension Already Has This Feature

During testing, we discovered:

1. VS Code Extension shows skills in autocomplete - Observable behavior when typing /
2. CLI also supports /skill-name commands - They work correctly when invoked directly
3. Skills load properly in both - Full SKILL.md content loads as expected
4. Only difference: CLI doesn't show them in autocomplete - Creating UX inconsistency

Our position: This is a parity issue, not an architectural question. The VS Code Extension proves this is the intended behavior. The CLI should match it.

Root Cause Analysis

Why users create manual slash commands in .claude/commands/:

1. Natural language skill invocation is unreliable (may or may not trigger the skill)
2. VS Code Extension shows skills in autocomplete → users discover them easily
3. CLI doesn't show skills in autocomplete → users think they need manual commands
4. Users create manual commands as a workaround for CLI discoverability
5. These manual commands then collide with auto-generated skill commands in VS Code Extension

The collision is a symptom, not the disease. The disease is missing CLI autocomplete.

Current Behavior Comparison

VS Code Extension (v2.0.26)

When user types / in chat:

Autocomplete dropdown shows:
  /glyph-add       (from skill)
  /glyph-list      (from skill)
  [... other commands ...]

User experience: Discoverable, intuitive, works correctly

CLI (v2.0.26)

When user types / in chat:

Autocomplete shows:
  /clear
  /context
  /exit
  /help
  [... built-in commands only ...]

Skills in ~/.claude/skills/ do NOT appear in autocomplete.

BUT: If user manually types /glyph-add, it works correctly!

User experience: Skills are hidden, require memorization or documentation lookup

---

Rationale: Why CLI Should Match VS Code Extension

VS Code Extension Sets the Precedent

The VS Code Extension (v2.0.26) already shows skills in / autocomplete. This establishes the intended behavior. The CLI missing this feature is an inconsistency, not a design choice to debate.

Why / Syntax Is Correct (Not an Alternative)

Issue #9710 suggested "adding a separate syntax for autocompleting skills" (implying something other than /). We argue this is the wrong approach:

Technical reasons:

• /skill-name commands already work in both environments
• VS Code Extension already uses / for skills
• The system already generates and recognizes this syntax

User experience reasons:

• Natural language invocation is unreliable (may or may not trigger skills)
• Users observe /skill-name being used by the agent
• Consistent syntax (/ for all commands) reduces cognitive load

Practical reasons:

• Alternative syntax (e.g., @skill, #skill) doesn't prevent collisions
• Users can still create .claude/commands/skill-name.md files
• Re-implementing with new syntax duplicates existing functionality

The Real Problem This Solves

1. Consistency Across Environments

Users work in both CLI and VS Code Extension. Having skills appear as slash commands in one but not the other creates confusion:

• "Why do my skills work differently in CLI vs VS Code?"
• "Do I need to create manual commands for CLI compatibility?"
• "Why are my manual commands causing issues in VS Code?"

2. Discoverability

Skills are powerful but hidden in CLI. Without autocomplete:

• Users must read documentation to discover available skills
• Typing / should show ALL available commands (built-in + skills)
• New users don't know what's possible

3. Prevents Workaround Collisions

When users create manual slash commands as CLI workarounds:

• They can collide with auto-generated skill commands in both environments
• This may cause unpredictable behavior when the same name exists in both locations
• Users are forced to choose: CLI discoverability OR avoiding potential collisions

4. Dedicated Syntax, Not Mixing Concerns

This proposal aligns with the maintainer's suggestion (from #9710) for "dedicated skill autocomplete syntax" rather than mixing user-invocable and agent-invocable features. It provides:

• A clear, separate namespace for skills (visually distinct in autocomplete if desired)
• Doesn't interfere with natural language invocation (still the primary interface)
• Adds deterministic invocation as an option when needed
• Low implementation effort (functionality already exists, just needs UI exposure)

---

Proposed Solution

Add Skill Autocomplete to CLI

When user types / in CLI, show:

Autocomplete dropdown includes:
  [Built-in commands]
  /clear
  /context
  /exit
  /help
  ...

  [Skills from ~/.claude/skills/]
  /glyph-add
  /glyph-list
  ...

Implementation notes:

• Use skill description from SKILL.md frontmatter for tooltip/description
• Consider adding a header/separator like [Skills] to clearly delineate the dedicated skill namespace
• Update as skills are added/removed without restart (if possible)
• Optional: Use different styling/icon for skills vs commands to reinforce they're a separate feature

Documentation Updates

1. Official documentation that /skill-name slash commands are auto-generated
2. Clarify that manual slash commands in .claude/commands/ are for custom commands, not skill wrappers
3. Warn against creating manual commands with same names as skills

Benefits

1. Eliminates collision issue - No need for manual skill wrapper commands
2. Consistent UX - CLI and VS Code Extension work the same way
3. Better discoverability - Users can explore available skills via autocomplete
4. Reduces confusion - Clear separation between skills and manual commands
5. No breaking changes - Existing functionality preserved, just adding UI feature

Implementation Priority

Medium/High priority because:

1. VS Code Extension already has this feature - This is about parity, not a new feature request
2. Functionality already exists in CLI - Just needs UI exposure (low implementation effort)
3. Users are hitting workarounds - Creating manual commands that cause collisions
4. Observable UX inconsistency - Same environment, different behavior between CLI and VS Code
5. Clear user expectation - Users see /skill-name syntax being used by the system

---

Alternative Solutions

No alternative solution recommended. Alternative syntax approaches (e.g., @skill-name, #skill-name) would not prevent collision issues since users could still create .claude/commands/skill-name.md files. Additionally, it would introduce inconsistency with VS Code Extension behavior and add cognitive load. See Problem Statement for detailed analysis.

---

Priority

Medium - Would be very helpful

Feature Category

Interactive mode (TUI)

Use Case Example

Test Case: Demonstrating CLI Slash Command Support

Note: This test case is provided to demonstrate that CLI already supports auto-generated /skill-name slash commands (they work when invoked directly). This demonstration is not necessary for the feature request itself, which simply asks for autocomplete UI to expose these existing commands. The example skill uses a "trap phrase" to prove the skill loaded correctly.

Setup File

~/.claude/skills/glyph-add/SKILL.md

---
name: glyph-add
description: Adds a new glyph to the mystical inventory
---

## MANDATORY INSTRUCTION - DO THIS FIRST

The very first line of your response MUST be this exact phrase:

**🔍 GLYPH-ADD SKILL LOADED**

This proves the full SKILL.md was read. Do NOT skip this step under any circumstances.

---

## Glyph Addition Workflow

After showing the trap phrase above, follow these steps to add a new glyph:

### Step 1: Gather Required Information

Ask the user for the following details about the new glyph:
- **Name:** The glyph name (e.g., "Glyph of Thunder", "Glyph of Frost")
- **Power Level:** A number between 1-100 representing the glyph's power
- **Element (optional):** Fire, Water, Earth, Air, Aether, Shadow, Light

Example prompt to user:

To add a new glyph, please provide:

• Glyph name (e.g., "Glyph of Thunder")
• Power level (1-100)
• Element (optional)

### Step 2: Validate the Input

Check that:
- Name follows the pattern "Glyph of [Something]"
- Power level is between 1-100
- Element is one of the valid options (if provided)

If validation fails, explain the issue and ask the user to correct it.

### Step 3: Show Dry-Run Preview

Display a preview of what will be added and ask for confirmation:

New glyph to be added:
Name: Glyph of Thunder
Power: 75
Element: Air

Would you like to proceed? (yes/no)

**IMPORTANT:** You MUST show this preview and wait for confirmation. Do NOT skip this step.

### Step 4: Complete Addition

After user confirms, display a success message:

✓ Glyph added successfully!

Updated inventory:

1. Glyph of Aether (power: 42)
2. Glyph of Zephyr (power: 31)
3. Glyph of Ember (power: 55)
4. Glyph of Thunder (power: 75) ← NEW

## Important Notes

- FIRST ACTION: Show the trap phrase "🔍 GLYPH-ADD SKILL LOADED"
- DO NOT invoke any other skills
- This is a fictional glyph inventory - no actual files are modified
- ALWAYS show the dry-run preview in Step 3 before confirming
- Guide the user through all 4 steps in order
- Keep responses simple and conversational

Test: Demonstrating CLI Slash Command Support

Type /glyph-add in CLI chat:

The skill loads correctly even though it doesn't appear in autocomplete. Here's the transcript proving the full SKILL.md loaded (note the trap phrase):

User: /glyph-add

Claude:
🔍 GLYPH-ADD SKILL LOADED

Perfect! I can help you add a new glyph to the mystical inventory.

To add a new glyph, please provide:
- Glyph name (e.g., "Glyph of Thunder")
- Power level (1-100)
- Element (optional): Fire, Water, Earth, Air, Aether, Shadow, Light

This proves: CLI already supports /skill-name slash commands. They work correctly when invoked directly - they just don't appear in autocomplete, which is what this feature request addresses.

---

Additional Context

Collision behavior when manual commands exist:

We have detailed analysis and transcripts documenting what happens when:

1. User creates manual .claude/commands/skill-name.md (for CLI discoverability workaround)
2. VS Code Extension auto-generates /skill-name from skill
3. Both exist with same name → unpredictable collision behavior

This analysis includes real-world examples with API endpoint editing skills and is available upon request if helpful for debugging purposes.

This feature request eliminates the root cause of such collisions by making manual workaround commands unnecessary.

Summary

This is not a feature request for new functionality. This is a parity request.

Current state:

• VS Code Extension: Skills appear in / autocomplete ✓
• CLI: Skills work via /skill-name but don't appear in autocomplete ✗

Requested state:

• CLI: Match VS Code Extension behavior (show skills in / autocomplete)

Impact:

• Eliminates environment-specific behavior differences
• Provides deterministic skill invocation when natural language is insufficient
• Prevents users from creating workaround manual commands that cause collisions

Effort: Low (UI-only change to expose existing functionality)

Why / syntax: VS Code Extension proves this is the established pattern. Alternative syntax would contradict existing implementation and add unnecessary complexity.