Feature Request: Enable Skill Tool to Discover Custom Project Skills in .claude/skills/

Description

Custom project skills placed in .claude/skills/ directories with properly formatted SKILL.md files (including YAML frontmatter with name and description fields) are not recognized by the Skill tool. The tool only recognizes the predefined "managed" skills (pdf, xlsx, docx, pptx, etc.) and returns "Error: Unknown skill" for custom project skills.

Current Behavior

⏺ Skill(clerk-auth-standard)
  ⎿  Error: Unknown skill: clerk-auth-standard

⏺ Skill(nonprofit)
  ⎿  Error: Unknown skill: nonprofit

⏺ Skill(pdf)
  ⎿  (Works - loads from managed skills list)

The Skill tool only works with skills listed in the <available_skills> section, which are managed/built-in skills.

Expected Behavior

The Skill tool should automatically discover and allow invocation of custom project skills that have:

1. A directory in .claude/skills/ with the skill name
2. A SKILL.md file with proper YAML frontmatter:

---
name: clerk-auth-standard
description: Implement Clerk authentication with RBAC, middleware protection, custom sign-in pages...
---

# Clerk Authentication Standard
[skill content...]

Reproduction Steps

1. Create a custom skill directory: .claude/skills/my-custom-skill/
2. Create SKILL.md with proper YAML frontmatter:

```yaml
---
name: my-custom-skill
description: Description of what this skill does and when to use it.
---

# My Custom Skill
Content here...
```

1. Try to invoke: Skill(my-custom-skill)
2. Observe: "Error: Unknown skill: my-custom-skill"

Environment

• Platform: macOS (Darwin 25.1.0)
• Claude Code Version: Latest (as of December 2024)

Use Case

We've built an enterprise boilerplate with 63+ custom project skills organized by domain (authentication, payments, shipping, database, etc.). These skills serve as knowledge bases for specialized agents invoked through slash commands.

Architecture:

Slash Commands → Agents → Skills (as knowledge base)

Examples of custom skills we've created:

• clerk-auth-standard - Authentication patterns
• stripe-connect-standard - Payment processing
• checkout-flow-standard - E-commerce checkout
• shopping-cart-standard - Cart management
• react-native-standard - Mobile development
• Plus 58 more domain-specific skills

Proposed Solution

1. Scan .claude/skills/ at startup - Discover all subdirectories with valid SKILL.md files
2. Register discovered skills - Add them to the available skills list alongside managed skills
3. Enable Skill tool invocation - Allow Skill(skill-name) for custom project skills
4. Support personal skills - Also scan ~/.claude/skills/ for user-level skills

Workaround

Currently, we work around this by:

1. Having agents read skill files manually with Read tool
2. Creating slash commands that orchestrate agents
3. Agents reference skills as inline knowledge (less maintainable)

This works but loses the automatic context-matching benefit that skills are supposed to provide.

Additional Context

According to Claude Code documentation, skills should be "model-invoked" based on context matching with the description field. However, this auto-discovery mechanism doesn't seem to be working for custom project skills - only for managed skills.

The documentation states:

"Custom project skills are automatically discovered through file system scanning... No configuration file or registration is required—the presence of a properly formatted SKILL.md file in either location makes the Skill immediately discoverable."

This doesn't match the observed behavior where custom skills return "Unknown skill" errors.

Impact

This feature would enable:

• Knowledge modularization - Separate concerns into focused skill files
• Team knowledge sharing - Share skills via git repositories
• Context-aware assistance - Claude automatically applies relevant skills
• Enterprise boilerplate systems - Reusable skill libraries across projects