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

[vanek-21-code]

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] 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. Ask a question that matches the skill description
3. Observe the assistant using generic tools instead of recognizing the SKILL.md

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

[github-actions[bot]]

Found 1 possible duplicate issue:

1. https://github.com/anthropics/claude-code/issues/9710

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

[vanek-21-code]

Might be the same issue, not sure.

[JacksonBates]

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.

[JacksonBates]

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.

[otrebu]

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.

[JacksonBates]

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.

[neongreen]

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.
---

[JesseCDev]

I have this exact problem, still not fixed regardless of what I try with descriptions.

[ajax-semenov-y]

+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:

This appears to be a bug in my opinion.

[spences10]

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.

[spences10]

Just trying on Linux Fedora too, clearly a bug!

[SuperRich]

Just to say I also experience this. Using Claude API via bedrock, I have setup a skills folder at root level in .claude folder and claude tells me it does not have any skills despite their quite clearly being multiple skills in that folder. I then had claude read over the docs and it tells me everything is set up correctly.

[jodosha]

I had the same problem: Error: Unknown skill foo.

Stopping ESC + /clear and retyping the same prompt, then just worked.

NOTE: before this failure, I reconnected an MCP server. After it picked the skill, Claude asked if I was allowing that skill to work in that directory. I already used it that codebase. 👉 My hypothesis is that the MCP reconnection somehow messed with allowed skills. 🤷

[CybotTM]

As described in #10568, claude code does have no problems finding the skills from anthropic skill marketplace, but did not recognize skills from my custom marketplace.

[CybotTM]

My workaround is to tell claude code to add all custom skills to the anthropic skill marketplace skill plugin.

See "Workaround 2: Inject Skills into Anthropic Marketplace ✅ WORKS" in https://github.com/anthropics/claude-code/issues/10568#issuecomment-3467326581

example prompt to tell claude code to add your skills: https://github.com/anthropics/claude-code/issues/10568#issuecomment-3467411762

[spences10]

heh! Ok, in Claude Code v2.0.31 if I remove the multiline description: it will list skills!

So, I guess it's my fault for not respecting YAML rules? But, Prettier did the formatting so, adding a # prettier-ignore will do it if you use that for formatting your files

[otrebu]

It is getting better the trigger, and this seems to help too:

 "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '\n\nIF THERE IS A SKILL FOR THIS USE IT! PLEASE CHECK.'"
          }
        ]
      }
    ]

Especially when you have some coding related skills, which they used to not be triggered for me.

[dellis23]

Can't get it to use skills, even for the skills it created!

[dellis23]

I should also say I've tried uploading the skills via the web UI, and I've tried putting the skills in both the project claude directory and the home user claude directory. To be clear, this is not a problem with it not automatically using them in the right context. Even if I explicitly tell it to use the skill it is unable to, and if I ask it what skills it has available it thinks it has none.

[spences10]

I should also say I've tried uploading the skills via the web UI, and I've tried putting the skills in both the project claude directory and the home user claude directory. To be clear, this is not a problem with it not automatically using them in the right context. Even if I explicitly tell it to use the skill it is unable to, and if I ask it what skills it has available it thinks it has none.

how is the frontmatter (YAML) formatted for the SKILL.md?

I found that this, is invalid:

whereas this is valid:

I made a CLI for Claude to use, (TypeScript) where you can say "Hey use pnpx claude-skills-cli to validate the skills in the project" use npx -y if you don't use pnpm it usually does an ok job of creating well structured skills to use

https://scottspence.com/posts/claude-code-skills-not-recognised

I also incorporated @otrebu's suggestion into the CLI

[SpaceGorilla404]

I was having this issue where some, but not all, skills were being recognized by Claude Code at session start. There is an undocumented (or poorly documented) 12500 character limit on metadata for ALL skills loaded by Claude Code, which can be independently confirmed through inquiry. A significant percentage of that 12500 budget is just formatting overhead you can't control. While this may not explain the reported bug in its entirety, checking for overage of this limit should be part of the debugging process. Hope that helps someone out there.

Update: the metadata character limit appears to be lower than I initially estimated and appears to be closer to 12500. After addressing this issue, I still am unable to have skills be recognized at session start without explicitly telling Claude to use skills, and so I consider this still a open bug that is open as that runs against the stated documented behavior. Combined with the windows bug (tracked elesewhere) that prevents automatically injecting such a command, this is quite frustrating.

[CybotTM]

I got it fixed for me, my skills are now properly recognized when installed via my marketplace. Maybe due to meta information changes in skill/marketplace or updates in claude code CLI. Claude Desktop is also happy with them.

So no more issues for me and my skills with Claude Code or Claude Desktop.

[towry]

Latest version have no issues, the Meta format is important.

[BernardVanTonder]

Definitely still broken on the latest - v2.0.36

[hoang-innomize]

I am also facing this issue; it is not clear why CC cannot discover skills. Right now, an inconsistent behavior I can detect is about the nested structure. To me, right now, it seems due to the nested structure, but according to the offical document, the complex skills can be groupped in the nested directories.

[spences10]

I am also facing this issue; it is not clear why CC cannot discover skills. Right now, an inconsistent behavior I can detect is about the nested structure. To me, right now, it seems due to the nested structure, but according to the offical document, the complex skills can be groupped in the nested directories.

Can you list them with <available_skills> in Claude Code?

See: https://github.com/anthropics/claude-code/issues/9716#issuecomment-3487826132

[dellis23]

No, the answer in that blog post is not the problem, for me at least.

[guyskk]

Maybe claude DO NOT KNOW whats skills yet. When I put some instructions about skills (eg: when to use xxx skills) in ~/.claude/CLAUDE.md then it will use the skills.

[SpaceGorilla404]

Maybe claude DO NOT KNOW whats skills yet. When I put some instructions about skills (eg: when to use xxx skills) in ~/.claude/CLAUDE.md then it will use the skills.

This is not a foolproof solution. I have done extensive cross referencing of skills, agents, and claude.md files and nothing seems to help Claude maintain or navigate the context available to it consistently -- which goes directly against all the marketing and spin around ALL of these features. God help you if he auto-compacts. In fact, an unrelated problem to this bug report is my pet peeve that Claude never wants to actually do the things instructed in .claude/CLAUDE.md.

It seems that Anthropics has been able to create ideas for managing context faster than making any of them actually work except in the most limited of minor context navigation tasks --- in which case why bother setting up any agent, skill, or claude.md documentation in the first place? It's beyond aggravating.

[spences10]

With over 300+ simulated tests and around 100+ manual tests I found the most reliable way to activate skills is with a forced evaluation hook

https://scottspence.com/posts/how-to-make-claude-code-skills-activate-reliably

I've added the hooks to the Claude Skills CLI use the following or ask Claude Code to add them:

# Default: forced-eval hook (84% success), global scope
pnpx claude-skills-cli add-hook

# Specify hook type and scope
pnpx claude-skills-cli add-hook --type llm-eval          # LLM eval, global
pnpx claude-skills-cli add-hook --type forced-eval --project   # Forced eval, project
pnpx claude-skills-cli add-hook --type simple-script --local   # Simple script, local