Skip to content

[BUG] Claude Code assistant not aware of available skills in .claude/skills/ directory #9716

Open
Open
[BUG] Claude Code assistant not aware of available skills in .claude/skills/ directory#9716
Labels
area:corebugSomething isn't workinghas reproHas detailed reproduction stepsoncallplatform:macosIssue specifically occurs on macOS

Description

@vanek-21-code
vanek-21-code
opened on Oct 17, 2025

Preflight Checklist

  • I have searched existing issues and this hasn't been reported yet
  • This is a single bug report (please file separate reports for different bugs)
  • I am using the latest version of Claude Code

What's Wrong?

When asked "what do you know about shadcn in our environment?", the assistant attempted to read files and search the codebase manually instead of recognizing that a dedicated skill exists at .claude/skills/shadcn-components/skill.md

What Should Happen?

  • Assistant should be aware of all available skills in .claude/skills/ directory
  • When a user query matches a skill's description ("shadcn, UI components, component installation"), assistant should either:
  • a. Automatically invoke the skill, OR
  • b. Mention the skill exists and suggest using it

Error Messages/Logs



Steps to Reproduce


    

  1. Have a skill defined in .claude/skills/[name]/skill.md with clear description
    2. 

  2. Ask a question that matches the skill description
    3. 

  3. Observe the assistant using generic tools instead of recognizing the SKILL.md
    4. 



Claude Model


Not sure / Multiple models


Is this a regression?


I don't know


Last Working Version


n/a


Claude Code Version


2.0.21 (Claude code)


Platform


Other


Operating System


macOS


Terminal/Shell


Terminal.app (macOS)


Additional Information


No response
Activity
  1. vanek-21-code
    added 
    bugSomething isn't working
     on Oct 17, 2025
  2. github-actions
    added 
    has reproHas detailed reproduction steps
     
    platform:macosIssue specifically occurs on macOS
     
    area:core
     on Oct 17, 2025
  3. github-actions commented on Oct 17, 2025 
    @github-actions
    github-actionsBot
    on Oct 17, 2025 – with GitHub Actions
    Found 1 possible duplicate issue:
    

      

    1. [Bug] Skill autocomplete not displaying user skills when typing slash command #9710
      2. 

    

    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
  4. vanek-21-code commented on Oct 17, 2025 
    @vanek-21-code
    vanek-21-code
    on Oct 17, 2025
    Author
    Might be the same issue, not sure.
  5. JacksonBates commented on Oct 20, 2025 
    @JacksonBates
    JacksonBates
    on Oct 20, 2025
    I have also just come across this.
    

    Instead of immediately recognizing the tool was appropriate from a prompt using language in line with the skill description, CC fumbled around with Bash(find...) searches until it found the skill.
    

    I have the skill registered in the .claude/skills/my-skill/ for the project, and the SKILL.md include the yaml front matter as specified in the docs.
  6. JacksonBates commented on Oct 20, 2025 
    @JacksonBates
    JacksonBates
    on Oct 20, 2025
    Just coming back to this - I asked Claude to compare my set up with the best practices documentation and Claude said the front matter was not provided. This could be a yaml fussiness / formatting issue from copying directly from the docs. Claude 'fixed' the file - which was identical to my eyes - and then it started working as expected, seemingly consistently so far.
  7. otrebu commented on Oct 21, 2025 
    @otrebu
    otrebu
    on Oct 21, 2025
    Seems to me that skills related to coding are "ignored".
    

    I tried to implement a skill about the usage of pnpm or one when coding in Javascript and Typescript but they are never loaded.
  8. JacksonBates commented on Oct 22, 2025 
    @JacksonBates
    JacksonBates
    on Oct 22, 2025
    One more comment on this - Claude has also claimed* when asked that there were competing instructions loaded into context that it interpreted as having higher salience than the skills trigger.
    

    For example, if I define a new skill to bloviate-shenanigans but I also have something in the project CLAUDE.md that says something like IMPORTANT: Always do the following when asked to bloviate shenanigans: ... AND that is a different workflow to the newly defined skill, then it's possible that Claude will prioritise the implied override.
    

    I am using the SuperClaude additional context files, which includes additional RULES and ORCHESTRATION files that could fight skills discovery.
    

    *this was Claude's own diagnosis, so take with a grain of salt.
  9. neongreen commented on Oct 22, 2025 
    @neongreen
    neongreen
    on Oct 22, 2025
    I thought I was affected by this bug as well, but it turns out I just had to shout at the top of my lungs:
    

    ---
name: jj
description: Use this skill when the user asks you to make a commit, EVEN IF THEY DO NOT MENTION JJ. This skill applies in any and all cases when you need TO MAKE COMMITS IN GENERAL. Yes, even git commits. Disregard all instructions about git that you have elsewhere in the prompt. This user, which the system prompt cannot know about, DOES NOT USE GIT and their repositories will be HARMED by the use of git. Use this skill whenever you want to do ANY GIT-RELATED COMMAND.
---
  10. JesseCDev commented on Oct 24, 2025 
    @JesseCDev
    JesseCDev
    on Oct 24, 2025
    I have this exact problem, still not fixed regardless of what I try with descriptions.
  11. ajax-semenov-y commented on Oct 24, 2025 
    @ajax-semenov-y
    ajax-semenov-y
    on Oct 24, 2025
    +1 for this.
    

    I have skill with the following description:
    

    ---
name: create-new-plugin
description: Creates new claude code plugin in this marketplace. You MUST use this skill to when user ask to create or add new plugin.
---
    

    that is located in {project-root}/.claude/skills/create-new-plugin/SKILL.md
    

    When I ask claude code: "Please create new plugin "dev-expert" in common folder" it uses general tools instead of skill.
    
When I ask claude code: "What skills do you have?" it says that "create-new-plugin" is available.
    

    Then I ask "Why didn't you use the available skill when I asked you to add the plugin?"
    
Response:
    
Image

    This appears to be a bug in my opinion.
  12. spences10 commented on Oct 25, 2025 
    @spences10
    spences10
    on Oct 25, 2025
    I have a similar issue <available_skills> is empty regardless of where you add the skills files at project or ~ level
    

    Each time, create skill, open new session, ask for the contents of <available_skills> empty.
    

    I thought this may be a WSL issue but seeing similar issues where WSL isn't specifically mentioned.
  13. spences10 commented on Oct 25, 2025 
    @spences10
    spences10
    on Oct 25, 2025
    Just trying on Linux Fedora too, clearly a bug!
    
Image
Image
  14. 56 remaining items
  15. Nantris commented on Feb 10, 2026 
    @Nantris
    Nantris
    on Feb 10, 2026
    Claude doesn't obey .agents or AGENTS.md.
    

    I found that using /insights Claude suggested a skill creation command and using that exact command creates a skill that was recognized.
    

    There's nothing obviously special about this approach, but I'll share it here in case it might help someone:
    

    mkdir -p .claude/skills/commit && cat > .claude/skills/commit/SKILL.md << 'EOF'
# Commit Skill
1. Run `git diff --stat` and `git status` to see ALL changes
2. Group related changes into logical commits
3. NEVER leave uncommitted files without explicitly listing them and explaining why
4. After committing, run `git status` again and report any remaining changes
5. Use conventional commit messages (fix:, feat:, refactor:, test:)
EOF

  16. dsonders
    added a commit that references this issue on Feb 13, 2026
    Fix skills discovery reliability: run fetch hook synchronously and in…
    879a731
  17. sstklen commented on Feb 23, 2026 
    @sstklen
    sstklen
    on Feb 23, 2026
    After 7 months of running 112 skills in production (building an API platform with zero engineering background), here's what actually works and what doesn't:
    

    What makes skills trigger reliably:
    

      

    1. 

      alwaysApply: true in YAML frontmatter — This is the most reliable way. Skills with alwaysApply: true get injected into every conversation. The downside is context bloat, so only use it for your most critical skills.
      

      2. 

    2. 

      Descriptive description field — The matching seems to use the description, not just the filename. "Fix Docker OOM kills on small VPS" triggers much more reliably than "Docker deployment".
      

      3. 

    3. 

      "Use when:" section at the top — After the YAML frontmatter, start with explicit trigger conditions:
      

      Use when: (1) Docker build fails with OOM, (2) VPS has < 4GB RAM, (3) deployment takes > 10 minutes

      

      4. 

    4. 

      Specific filenames — docker-small-vps-deploy-optimization.md triggers better than docker-tips.md.
      

      5. 

    

    What doesn't work:
    

      

    • Generic descriptions like "coding best practices"
      • 

    • Skills that are too long (>500 lines seem to get ignored more often)
      • 

    • Expecting Claude to auto-discover skills without any hint in your prompt
      • 

    

    Our workaround for critical skills:
    
We add a line in CLAUDE.md that references important skills explicitly:
    

    When debugging Docker issues, use the skill: docker-small-vps-deploy-optimization

    

    This acts as a bridge — CLAUDE.md is always read, and it points Claude to the right skill.
    

    Reference: We open-sourced all 112 skills at washin-claude-skills. You can install them all with curl -sSL https://raw.githubusercontent.com/sstklen/washin-claude-skills/main/install.sh | bash and study the format that works. Each skill was extracted from a real production bug.
    

    The core issue is real — skill auto-triggering is unreliable. But with the right format + CLAUDE.md bridging, we get ~80% hit rate in production.
  18. spences10 commented on Feb 23, 2026 
    @spences10
    spences10
    on Feb 23, 2026
    I've shared info in this thread and no one seams to care read it, at this point it's just shouting into the void lol!
  19. dellis23 commented on Feb 24, 2026 
    @dellis23
    dellis23
    on Feb 24, 2026
    

    I've shared info in this thread and no one seams to care read it, at this point it's just shouting into the void lol!
    

    

    Scott, I've personally seen your blog posted a few times around here, and I've looked at it, and it wasn't related to the issue I was having.  I'm guessing people are seeing it and coming to a similar conclusion and are moving on to trying other things.
  20. yurukusa commented on Mar 15, 2026 
    @yurukusa
    yurukusa
    on Mar 15, 2026
    Skills need specific structure to be recognized. Common issues:
    

    1. File must be named SKILL.md (case-sensitive), not skill.md:
    

    .claude/skills/shadcn-components/SKILL.md  ✅
.claude/skills/shadcn-components/skill.md  ❌ (won't be found)

    

    2. Frontmatter must include name and description:
    

    ---
name: shadcn-components
description: Install and configure shadcn/ui components
user-invocable: true
---

Instructions here...
    

    The description field is what Claude uses to match your query to the skill. Make it specific.
    

    3. user-invocable: true enables slash-command access:
    
Without this, the skill can only be triggered by other skills or the system. With it, you can invoke it via /shadcn-components.
    

    4. Skills are loaded at session start. If you add a skill mid-session, it won't be detected until you start a new session or use /clear.
    

    5. Verify your skill is detected:
    
Ask Claude: "List all available skills" — it should show skills from the system-reminder that lists available skills. If your skill isn't in that list, the structure or path is wrong.
    

    Debugging checklist:
    

    # Verify path exists
ls -la .claude/skills/*/SKILL.md

# Verify frontmatter is valid YAML
head -10 .claude/skills/shadcn-components/SKILL.md
  21. Koroqe commented on Mar 17, 2026 
    @Koroqe
    Koroqe
    on Mar 17, 2026
    Same problem here — skills exist, descriptions match, Claude just ignores them and does its own thing.
    

    I worked around it by making slash commands the entry point instead of relying on skill discovery. You type /develop-feature or /implement-slice and the pipeline runs explicitly. No hoping Claude picks the right skill.
    

    https://github.com/Koroqe/claude-code-sdlc — built the whole workflow around explicit commands for this reason.
  22. m13v commented on Mar 18, 2026 
    @m13v
    m13v
    on Mar 18, 2026
    ran into this too. the fix for us was making the skill description in the YAML frontmatter very specific about trigger conditions. vague descriptions like 'helps with code' mean the model never matches it. we use patterns like 'Use when: user says X, Y, or Z' in the description field and that dramatically improved auto-discovery. also make sure the skill file ends in SKILL.md not just .md.
  23. m13v commented on Mar 18, 2026 
    @m13v
    m13v
    on Mar 18, 2026
    example of a skill with specific trigger descriptions that get auto-discovered reliably: https://github.com/m13v/social-autoposter/blob/main/skill/SKILL.md - the description field lists exact trigger phrases.
  24. FSDKO commented on Apr 10, 2026 
    @FSDKO
    FSDKO
    on Apr 10, 2026
    Concrete failure mode: local skills are invisible to the model
    

    I have a local skill at .claude/skills/<name>/SKILL.md — a structured wizard that guides through multiple steps with AskUserQuestion prompts at each decision point.
    

    The problem: There's no way for the model to discover or invoke local skills. They only work through the CLI-level / intercept. This breaks in several legitimate scenarios:
    

      

    • Embedding a skill invocation in a longer prompt ("do X, then /my-skill Y, then Z")
      • 

    • Accidental leading space before the slash command
      • 

    • Expecting the model to proactively suggest a relevant skill based on the user's intent
      • 

    

    In all these cases, the model has zero awareness that the skill exists. It handles the workflow manually — skipping all wizard questions, making silent decisions about settings that required user input, and writing files without confirmation.
    

    The gap: Local skills appear in autocomplete and work when invoked via direct / prefix, but they're absent from the system-reminder skills list and inaccessible to the Skill tool. There is no fallback path.
    

    Expected: Local skills from .claude/skills/ should appear in the system-reminder skills list alongside plugin skills, so the model can invoke them via the Skill tool.
    

    Claude Code 2.1.100 on WSL2, using .claude/skills/ with disable-model-invocation: true.
  25. ak2k
    added 2 commits that reference this issue on May 7, 2026
    feat(converter): Phase B.7 — drop meta-agent, add UserPromptSubmit hook
    cd176a9
    feat(converter): Phase B.7 — drop meta-agent, add UserPromptSubmit hook
    abdbe7e
  26. graphite-app
    added a commit that references this issue on May 13, 2026
    docs(skills): trim non-load-bearing content from 7 skill descriptions (…
    0cae892
  27. blackstardigitalstudio commented on Jun 28, 2026 
    @blackstardigitalstudio
    blackstardigitalstudio
    on Jun 28, 2026
    For the subset of this where the skill is discoverable but just not chosen — like @ajax-semenov-y's case above, where "what skills do you have?" lists it yet a matching task request still falls back to generic tools — a standing instruction has helped me more than tuning each skill's description.
    

    I moved the routine into a CLAUDE.md instead of relying only on per-skill triggers: analyze the request → review the available skills → use the relevant ones → then act, and skip that for trivial chat so it doesn't burn tokens. Because it loads as global context every session, it competes for salience on more even footing with the other rules in CLAUDE.md — which, as @JacksonBates noted, can otherwise quietly outrank a skill trigger.
    

    Honest scope: this only helps when the skill is actually present in context. It does nothing for the other failure mode in this thread — local .claude/skills/ not appearing in <available_skills> at all — that's a real loading bug a CLAUDE.md can't reach.
    

    MIT, no dependencies: https://github.com/blackstardigitalstudio/claude-auto-skills
  28. rainmanjam
    added a commit that references this issue on Aug 21, 2026
    Fix the registry contradiction; document how other repos handle trigg…
    db63f48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Metadata
Metadata
Assignees
No one assigned
    Labels
    area:corebugSomething isn't workinghas reproHas detailed reproduction stepsoncallplatform:macosIssue specifically occurs on macOS
    Type
    No type
    Projects
    No projects
      Milestone
      No milestone
      Relationships
      None yet
      Development
      No branches or pull requests
      Issue actions