Claude Code does not recognize its own skills feature (~/.claude/skills/)

[brunosantoscodexforgeceo]

Problem

When asked about available skills, Claude Code lists skill names from the system reminder but treats them as "slash commands" or confuses them with sub-agents. It has no awareness that skills are files in ~/.claude/skills/ and cannot describe what the skills feature actually is.

Expected Behavior

Claude should:

1. Understand that skills are user-defined files in ~/.claude/skills/
2. Be able to read and describe skill files
3. Distinguish skills from slash commands and sub-agent types
4. Recognize when asked "what skills are available?" that the user is asking about files in ~/.claude/skills/

Actual Behavior

Claude lists items from the system reminder (e.g., /run-tests, /deploy-to-servidor) and calls them "skills" when they are actually slash commands or sub-agents. It completely forgets that skills are files stored in ~/.claude/skills/.

Evidence

User has skill files in ~/.claude/skills/:

$ ls ~/.claude/skills
calculate-coverage    deploy-bcl-packages.md    post-merge-cleanup    pre-pr-review        run-tests
coderabbit-workflow    performance-testing    pr-merger        qodana-local-review    speckit-autopilot.md

When asked "what skills are available?", Claude listed system reminder items instead of reading these files.

Environment

• Claude Code CLI: Latest version
• Model: claude-sonnet-4-5-20250929
• Platform: macOS (Darwin 25.2.0)

Impact

Users cannot get help with their custom skills because Claude doesn't recognize the feature exists.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Claude Code assistant not aware of available skills in .claude/skills/ directory #9716
2. System prompt conflates skills and slash commands in <available_skills> #16072
3. Plugin skills not injected into <available_skills> context #15178

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[mlgualtieri]

I've also run into this same issue, version 2.1.39 on Linux.

[sstklen]

This is a real problem. Claude treats skills as abstract concepts rather than actual files it can read.

Practical workaround that works for us (112 skills in production):

In your CLAUDE.md, add an explicit skills index:

## Available Skills

The following skills are installed in ~/.claude/skills/:
- docker-small-vps-deploy-optimization: Fix Docker OOM on small VPS
- hono-subrouter-auth-isolation: Fix auth bypass in Hono sub-routers
- bun-sqlite-transaction-await-crash: Fix crash from await inside db.transaction()

When you encounter a problem that matches a skill, READ the skill file first before attempting to fix it.

This works because CLAUDE.md is always loaded into context. When Claude sees a matching problem description, it knows to Read ~/.claude/skills/skillname.md.

It's not ideal — skills should work automatically. But until the underlying issue is fixed, this CLAUDE.md bridging approach gives us ~80% success rate.

If you want to see the format that works, we open-sourced our full collection: 112 battle-tested skills. Each has YAML frontmatter + clear trigger conditions.