[FEATURE] SKILL Tool should recognize local skills in ~/.claude/skills/

[FEATURE] SKILL Tool should recognize local skills in ~/.claude/skills/

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a feature request, not a bug report
• I am using the latest version of Claude Code

What's Wrong?

Summary

The Skill tool only recognizes installed plugins, not local skills in ~/.claude/skills/. This prevents users from using custom skills without packaging them as full plugins.

Environment

• OS: Linux (WSL2) - Ubuntu
• Claude Code Version: 2.1.12
• Installation Type: Standard
• Working Directory: ~/.claude (also affects project directories)

Problem Description

Current Behavior

When attempting to invoke a local skill using the Skill tool:

Skill("code-review-agent-v002")

Error: Error: Unknown skill: code-review-agent-v002

The skill file exists at:

~/.claude/skills/development/code-review-agent-v002/SKILL.md

With valid frontmatter:

---
name: code-review-agent-v002
description: Context-resilient codebase review agent...
---

Root Cause

The Skill tool only recognizes skills from installed plugins, not from the local ~/.claude/skills/ directory.

Evidence from settings.json:

{
  "enabledPlugins": {
    "code-review@claude-plugins-official": true,  // ← Recognized (plugin)
    // No entry for local skills!
  }
}

Debug Log Evidence

[DEBUG] Loading skills from directories: managed=..., user=~/.claude/skills, project=...
[DEBUG] Total plugin skills loaded: 15
[DEBUG] Loaded 48 unique skills (managed: 0, user: 47, project: 0, duplicates removed: 14)
[DEBUG] Skills and commands included in Skill tool: 0  // ← Problem!

Observation: 48 skills are loaded from disk, but 0 skills are included in the Skill tool.

Expected Behavior

The Skill tool should recognize local skills in ~/.claude/skills/ just like it recognizes plugin skills.

Skill("code-review-agent-v002")
// Should work! The skill exists at ~/.claude/skills/development/code-review-agent-v002/SKILL.md

Actual Behavior

Error: Unknown skill: code-review-agent-v002

Users must fall back to manual invocation:

1. Read the SKILL.md file
2. Follow the workflow manually
3. Or invoke the orchestrator script directly

Impact

This prevents users from:

• Quickly iterating on local skills during development
• Testing skills before packaging them as plugins
• Using personal skills without plugin overhead
• Distributing skills via simple file copy (vs plugin installation)

Use Cases

Use Case 1: Skill Development

When developing a new skill, users want to test it immediately without:

• Creating a full plugin structure
• Publishing to a marketplace
• Installing via claude plugin install

Use Case 2: Personal Skills

Users have personal/team-specific skills that:

• Are not suitable for public distribution
• Don't need plugin features (commands, hooks, agents)
• Should just work when placed in ~/.claude/skills/

Use Case 3: Rapid Iteration

Developers want to:

1. Edit SKILL.md
2. Test immediately with Skill("my-skill")
3. Repeat

Without plugin installation overhead.

Suggested Implementation

Option 1: Auto-Register Local Skills (Preferred)

The Skill tool should automatically discover skills in:

1. ~/.claude/skills/**/*.md
2. .claude/skills/**/*.md (project-local)
3. .claude-plugin/skills/**/*.md (plugin)

Precedence: Project-local → User → Plugin

Option 2: skills.json Registration File

Users manually register skills in ~/.claude/skills.json:

{
  "skills": [
    {
      "name": "code-review-agent-v002",
      "path": "~/.claude/skills/development/code-review-agent-v002/SKILL.md"
    }
  ]
}

Option 3: Auto-Discovery with Caching

1. Scan ~/.claude/skills/ on startup
2. Cache skill names in memory
3. Re-scan when files change (file watcher)

Workaround

Currently, users must:

1. Detect Skill Tool Failure:

``javascript
try {
Skill("my-skill")
} catch (error) {
// Fallback to manual execution
}
``

1. Manually Execute Skill:

```bash
# Read SKILL.md
Read("~/.claude/skills/my-skill/SKILL.md")

# Follow workflow manually
# Or invoke orchestrator script directly
bash ~/.claude/skills/my-skill/scripts/orchestrator.sh
```

1. Document Fallback in SKILL.md:

(See: Modified SKILL.md)

Related Issues

• #11620 - Windows: Skills not loading (different issue - 0 skills loaded)
• #10061 - Sub-agents load global vs project-local (related - skill resolution)

Key Difference

| Issue | Problem | Platform |
|-------|---------|----------|
| #11620 | 0 skills loaded (Windows path bug) | Windows |
| #10061 | Wrong skill source (global vs project) | All |
| This Request | Skill Tool doesn't recognize local skills | Linux/macOS/Unix |

Example: Improved Fallback Behavior

I've added a "Fallback: When Skill is Not Registered" section to the affected skill:

## ⚠️ Fallback: When Skill is Not Registered

**Problem:** When `Skill("code-review-agent-v002")` returns "Unknown skill"

**Mandatory Fallback Protocol:**

1. **Read SKILL.md** - `Read(~/.claude/skills/development/code-review-agent-v002/SKILL.md)`
2. **ASK USER** - Use `AskUserQuestion` to determine execution mode
3. **Execute** - Based on user choice (Full Review vs Analyze Only)

**FORBIDDEN:**
- ❌ NEVER: Auto-decide `--analyze-only` without asking
- ❌ NEVER: Skip user confirmation without explicit request

**ALWAYS:**
- ✅ AskUserQuestion first
- ✅ Let user decide between Full Review and Analyze Only

This demonstrates the workaround, but the root cause remains: The Skill tool should recognize local skills automatically.

Additional Context

Why This Matters Now

The code-review-agent-v002 skill is a complex, production-ready skill with:

• Fix Loop with context isolation
• E2E test execution
• Runtime error detection
• Self-healing capabilities
• 544 lines of well-documented workflow

Users should be able to invoke it with:

Skill("code-review-agent-v002")

Instead of requiring:

// Manual fallback (current workaround)
Read("~/.claude/skills/development/code-review-agent-v002/SKILL.md")
// Then follow workflow manually...

Skills vs Plugins

| Aspect | Skills | Plugins |
|--------|--------|---------|
| Structure | Single SKILL.md file | Full .claude-plugin/ structure |
| Features | Skill invocation only | Commands, hooks, agents |
| Discovery | Manual (~/.claude/skills/) | Automatic (installed) |
| Use Case | Quick workflow definition | Full-featured extensions |

Proposal: Local skills should be discoverable by the Skill tool, just like plugin skills are.

---

What Should Happen?

The Skill tool should recognize local skills in ~/.claude/skills/ automatically, without requiring plugin installation.

Error Messages/Logs

Error: Unknown skill: code-review-agent-v002

Steps to Reproduce

1. Create a skill at ~/.claude/skills/test-skill/SKILL.md:

```markdown
---
name: test-skill
description: A minimal test skill
---

# Test Skill

This is a test skill.
```

1. Attempt to invoke it:

``javascript
Skill("test-skill")
``

1. Expected: Skill loads successfully
2. Actual: Error: Unknown skill: test-skill

1. Verify skill exists:

``bash
cat ~/.claude/skills/test-skill/SKILL.md
# Output: The skill file exists and is readable
``

Claude Model

Sonnet (default)

Is this a regression?

No, this never worked

Last Working Version

N/A

Claude Code Version

2.1.12

Platform

Anthropic API

Operating System

Linux (WSL2 - Ubuntu)

Terminal/Shell

Bash

Additional Information

See also:

• CLAUDE.md - Skill Index
• Agent-Skill Integration Guide