User skills in ~/.claude/skills/ not auto-discovered

Resolved 💬 3 comments Opened Nov 8, 2025 by pitcany Closed Nov 12, 2025

Bug Report: User Skills in ~/.claude/skills/ Not Auto-Discovered

Summary

User skills placed in ~/.claude/skills/ with proper structure (skill-name/SKILL.md) are not automatically discovered or loaded into Claude's context, despite documentation stating they should be.

Environment

Claude Code Version: 2.0.35
Platform: macOS 15.1 (Darwin 25.1.0)
Architecture: arm64 (Apple Silicon)
Date: 2025-11-08

Expected Behavior

According to the official documentation at https://code.claude.com/docs/en/skills:

"Skills are automatically discovered by Claude from three sources: Personal Skills: ~/.claude/skills/, Project Skills: .claude/skills/, Plugin Skills: bundled with installed plugins."

Expected: Skills in ~/.claude/skills/ should be:

Automatically discovered by Claude Code
Available in Claude's context as "model-invoked" skills
Automatically loaded when relevant to user requests (similar to marketplace plugin skills)

Actual Behavior

Observed: Skills in ~/.claude/skills/ are:

NOT automatically present in Claude's context
NOT discoverable via the Skill tool (Unknown skill: skill-name error)
Require explicit loading via Read tool when user mentions the skill name

Skills Structure

User skills are properly formatted following Anthropic's skill-creator guidelines:

~/.claude/skills/
├── data-analysis-workflow/
│   ├── SKILL.md
│   └── references/
│       ├── numpy-patterns.md
│       ├── pandas-patterns.md
│       └── ...
├── postgresql-data-ops/
│   ├── SKILL.md
│   └── references/
│       └── ...
└── r-statistical-computing/
    ├── SKILL.md
    └── references/
        └── ...

Each SKILL.md has proper YAML frontmatter:

---
name: data-analysis-workflow
description: This skill should be used when working with NumPy arrays, pandas DataFrames, or building machine learning pipelines...
---

# Data Analysis Workflow
...

Reproduction Steps

Create a skill directory in ~/.claude/skills/:

``bash mkdir -p ~/.claude/skills/test-skill``

Create a SKILL.md file with valid frontmatter:

```bash
cat > ~/.claude/skills/test-skill/SKILL.md <<EOF
---
name: test-skill
description: This skill should be used for testing skill discovery.
---

# Test Skill
This is a test skill to verify auto-discovery.
EOF
```

Start a new Claude Code conversation

Ask Claude: "What skills are available?"

Expected Result: test-skill appears in the list of available skills

Actual Result: test-skill does not appear; only marketplace plugin skills are shown

Try to use the skill programmatically:

Attempt: Use the Skill tool with skill: "test-skill"
Result: "Unknown skill: test-skill"

Alternative approach that works:

Say: "Use the test-skill skill"
Claude must manually load it via: Read ~/.claude/skills/test-skill/SKILL.md

Comparison with Marketplace Skills

Marketplace skills (e.g., from superpowers-marketplace):

✅ Automatically present in Claude's context
✅ Discoverable via Skill tool
✅ Model-invoked (Claude uses them based on request relevance)

User skills (in ~/.claude/skills/):

❌ NOT automatically present in context
❌ NOT discoverable via Skill tool
❌ Require explicit mention and manual Read operation

Impact

This behavior means:

Users cannot create personal skills that work like marketplace skills
The documented "Personal Skills" feature doesn't function as described
Skills must be manually loaded, defeating the "model-invoked" pattern
There's no difference between putting skills in ~/.claude/skills/ vs anywhere else

Possible Root Causes

Feature not implemented: Auto-discovery for ~/.claude/skills/ may not be implemented yet
Documentation inaccurate: Docs may incorrectly describe the intended behavior
Missing initialization: Skills might need to be "installed" or registered somehow
Skill tool limitation: The Skill tool may only work with marketplace plugins by design

Workaround

Currently, users can:

Explicitly mention the skill name: "Use the data-analysis-workflow skill"
Claude manually loads it via Read tool
Skill content is applied to the task

This works but doesn't provide the automatic, model-invoked behavior described in documentation.

Questions for Maintainers

Is auto-discovery of ~/.claude/skills/ implemented in the current version?
If not, is this a planned feature?
Should the documentation be updated to clarify the difference between user skills and marketplace skills?
Is there a required registration/installation step for user skills that's not documented?

Additional Context

All 6 user skills follow the structure from anthropic-agent-skills marketplace
Skills were created using patterns from the skill-creator skill
Marketplace plugins are properly discovered (superpowers, elements-of-style, etc.)
User skills work when explicitly loaded via Read tool