If a Claude Code skill is not loading, first separate three different failures: Claude cannot discover the skill, it discovers the skill but does not select it, or it selects the skill but cannot complete its instructions. Rewriting the prompt repeatedly will not fix a file in the wrong directory.
This guide is for Claude Code in a local project. A skill uploaded to a different Claude product is not evidence that your terminal session has access to it. Start with a small diagnostic skill, then add your real workflow back one piece at a time.
Quick diagnosis: what exactly is failing?
| Symptom | First check | Useful next action |
|---|---|---|
| Skill cannot be invoked | File location and name | Create the minimal example below |
| Direct invocation works, natural requests do not | Description and invocation controls | Describe the actual user task |
| Skill starts but a script fails | Script path and prerequisites | Run the documented check separately |
| Wrong skill is selected | Overlapping descriptions | Give each skill a distinct responsibility |
| Works in one repository only | Project versus personal scope | Compare the installed locations |
Do not change all five variables together. Keep a short record of the symptom, the change, and the result so you know which change actually helped.
1. Verify the skill directory
For a project skill, the expected structure is:
your-project/
.claude/
skills/
check-instructions/
SKILL.md
A personal skill can live under ~/.claude/skills/. Project skills live under .claude/skills/. The filename is SKILL.md, inside its own directory. Descriptions help Claude select a skill, while a direct slash invocation lets you request it explicitly. These conventions are documented in the official Claude Code skills guide.
Check the actual filename in your file manager or terminal. A hidden extension can turn SKILL.md into SKILL.md.txt. Also confirm that the terminal is in the repository you intended to use. A skill installed in a sibling project is an easy mistake when several checkouts have similar names.
2. Try a skill with no external dependencies
Create this original diagnostic example in .claude/skills/check-instructions/SKILL.md:
---
name: check-instructions
description: Check whether a project skill can be invoked and return a fixed diagnostic marker.
---
Respond with: CHECK_INSTRUCTIONS_READY
Do not read files, run commands, or edit the repository.
Start a fresh Claude Code session from the project and enter /check-instructions. The expected result is the marker. This test does not prove that every instruction in your real skill will work; it isolates basic discovery and invocation from dependencies such as Python, API keys, or a browser connection.
If this minimal skill is available but the original is not, compare their directory structure and frontmatter. If neither is available, investigate the installation scope and your local Claude Code configuration before rewriting workflow instructions.
3. Make the description match the request
A description such as “Expert productivity helper” gives little information about when a skill should run. A more useful description names the input, the requested action, and the output:
description: Review a CSV export for missing identifiers, duplicate rows, and inconsistent date formats, then produce an issue report without changing the source file.
Try a request that matches that description: “Review this CSV export for missing identifiers and duplicate rows.” If direct invocation succeeds but this request does not, you have narrowed the problem to selection rather than installation.
Avoid stuffing every related keyword into the description. A skill that claims to handle writing, coding, spreadsheets, research, and deployment competes with almost every task. Split unrelated responsibilities into separate skills with clear boundaries.
4. Inspect invocation controls
The official skill format includes disable-model-invocation and user-invocable controls. A skill intentionally configured for manual use should not be expected to trigger automatically. Inspect these fields before deciding that selection is broken. See the invocation controls in the skills reference.
For your first diagnostic example, leave those optional controls out. Add them only after you have confirmed the default behavior. This gives you a working baseline instead of a mixture of installation problems and intentional restrictions.
5. Separate loading from execution
Once Claude begins following the skill, the next failure may have nothing to do with discovery. A missing executable, a relative path interpreted from the wrong directory, or an unavailable connector can stop a correctly loaded skill.
Use an execution checklist:
- Identify the exact step that failed and preserve its error message.
- Confirm that referenced helper files are included with the skill.
- Check the prerequisites the workflow actually needs.
- Run a harmless read-only example before any write operation.
- Explain the required output so success can be checked objectively.
For example, a CSV audit skill should first report the header names and row count. If it cannot do that, a ten-step cleanup workflow is premature. Make each dependency observable before building a larger process around it.
A better support report
When you need help, share the Claude Code version, operating system, project-relative skill path, frontmatter, invocation used, and the exact failure. Remove secrets and private file contents. “It does not work” gives someone very little to reproduce; a minimal skill and a precise symptom usually identify the next useful check.
You can browse reusable Claude skills for workflow ideas. If a skill loads but broader repository instructions are being missed, continue with CLAUDE.md not being followed.
FAQ
Why does my skill work only when I invoke it directly?
Discovery may be working while automatic selection is not. Check the description and invocation controls, then try a request that clearly matches the skill's stated task.
Should I reinstall everything when a skill does not load?
Start with a minimal project skill and verify its path. Reinstalling unrelated tools before isolating the failure adds variables and may leave the original problem unchanged.
Does a successful marker test prove my full skill works?
No. It confirms a narrow discovery and invocation path. Test scripts, inputs, permissions, and output validation separately.