[FEATURE] Improve Skills UX: Directory-based Skill Invocation

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

Problem

Skills are defined as individual markdown files within a directory (e.g., /skills/vuln-review/vuln-review-swift-security.md), but users must invoke them using the exact filename. This creates usability issues:

1. Discoverability: Users don't know what skills are available without listing directory contents
2. Memorization burden: Users must remember long, specific filenames like vuln-review-swift-security instead of intuitive categories like vuln-review
3. Error-prone: Typos in skill names lead to "Unknown skill" errors
4. Counter-intuitive: The natural mental model is "I have a vuln-review skill" (the directory) not "I have 14 different vuln-review-* skills"

Current Behavior

User: "Can you do a security review?"
Claude: Invokes skill "vuln-review"
Result: Error: Unknown skill: vuln-review

The skill system looks for a file named vuln-review.md but finds a directory named vuln-review/ containing multiple specialized skill files.

Expected Behavior

Users should be able to invoke skills at the directory level, and the system should either:

Option A: Index/Entry Point Pattern

• When invoking a directory-based skill, look for an index file (e.g., vuln-review/vuln-review.md or vuln-review/index.md)
• The index file contains instructions for which specialized skills to invoke based on context

Option B: Automatic Discovery

• Invoking a directory skill automatically loads all .md files within that directory
• Each file's instructions are available in the context

Option C: Interactive Selection

• Invoking a directory skill presents the user with available sub-skills
• User can select which ones to run

Proposed Solution

Proposed Solution

Option A (index/entry point) seems most flexible:

1. Skills can be organized hierarchically: /skills/vuln-review/vuln-review-swift-security.md
2. Users invoke the category: vuln-review
3. System looks for /skills/vuln-review/vuln-review.md (matches directory name) or /skills/vuln-review/index.md
4. The entry point file contains logic to determine which specialized skills to invoke
5. Falls back to treating it as a single skill if no entry point exists (backward compatible)

Alternative Solutions

Workaround

Currently, users must create a wrapper skill manually at /skills/vuln-review/vuln-review.md that contains instructions for invoking the specialized skills. This works but requires boilerplate for every skill category.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

Use Case

Security vulnerability reviews naturally group into categories:

• General category: "vuln-review"
• Specialized reviews: "vuln-review-swift-security", "vuln-review-swift-xpc", "vuln-review-filesystem-toctou", etc.

Users should say "run a security review" not "run vuln-review-swift-security, then vuln-review-swift-xpc, then vuln-review-swift-filesystem, then..."

Additional Context

Benefits

1. Better UX: Intuitive invocation matching mental models
2. Easier organization: Skills can be grouped logically
3. Reduced errors: Fewer chances for typos
4. Scalability: Categories can contain many specialized skills without overwhelming users
5. Backward compatible: Single-file skills continue to work

Related

This is similar to how many systems handle hierarchical commands:

• Python packages with __init__.py
• Node.js packages with index.js
• Web servers with index.html