Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [BUG] unclear how to make CC discover skills [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#45161•Fetched 2026-04-09 08:11:53
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
perhmmperhmm
Participants
perhmmperhmm
Timeline (top)
labeled ×4

Error Message

Error Messages/Logs

Fix Action

Fix / Workaround

Workaround for project-level skills: .claude/skills/ files can be referenced via @. No equivalent workaround exists for user-level skills.

RAW_BUFFERClick to expand / collapse

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?

Skills in ~/.claude/skills/ that are not user-invokable are listed in /skills and highlighted in blue when referenced by name (e.g., /review-checklist) in messages. However:

  1. The blue highlighting doesn't load the skill contents into context — Claude sees plain text
  2. Since the skill isn't user-invokable, typing /review-checklist as a command errors out
  3. @ file references only list project directory files, so ~/.claude/skills/ files can't be referenced that way

This creates a dead end: the terminal visually signals that the reference is recognized, but there's no mechanism to actually get the skill contents into context.

How the issue manifests

When referencing a non-invokable user-level skill in natural language (e.g., "Please review branch BUG-1234 according to /review-checklist"), Claude does not load the skill. Instead it either treats the reference as plain text and proceeds without the skill's guidance, or searches the codebase for the concept (e.g., searching for "review checklist" in files) and may coincidentally find the skill file — but this is unreliable and not guaranteed.

The blue highlighting in the terminal gives the impression the reference is understood, so the user may not realize the skill wasn't loaded until they notice Claude's output doesn't follow the skill's instructions.

Workaround for project-level skills: .claude/skills/ files can be referenced via @. No equivalent workaround exists for user-level skills.

What Should Happen?

Expected behavior: Either the blue highlighting should load the skill into context, or there should be another mechanism (e.g., @ support for user-level files) to reference them.

Error Messages/Logs

Steps to Reproduce

Reproduction:

  1. Create a non-invokable skill at ~/.claude/skills/review-checklist.md
  2. In a message, reference it naturally: "Please review branch BUG-1234 according to /review-checklist"
  3. Observe that /review-checklist is highlighted in blue in the terminal
  4. Observe that Claude does not load or follow the skill's contents

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.1.96

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other

Additional Information

Running CC in a ZED Terminal

extent analysis

TL;DR

The issue can be mitigated by adding support for referencing user-level skills via a mechanism similar to @ for project-level skills.

Guidance

  • Investigate modifying the @ reference mechanism to support user-level skills in ~/.claude/skills/.
  • Consider adding a new syntax or command to load non-invokable user-level skills into context.
  • Verify that the blue highlighting is not misleading by ensuring it only appears when the skill can be loaded into context.
  • Review the documentation for the Opus Claude Model and Anthropic API to see if there are any existing mechanisms or workarounds for referencing user-level skills.

Example

No code snippet is provided as the issue does not imply a specific code change.

Notes

The issue may be related to the specific version of Claude Code (2.1.96) or the Opus Claude Model, but without more information, it's difficult to determine the root cause.

Recommendation

Apply a workaround by modifying the reference mechanism to support user-level skills, as there is no clear indication that upgrading to a fixed version will resolve the issue. This is because the issue is not clearly identified as a regression, and the last working version is not specified.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#tool integration#LLM response#prompt template#agent execution

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING