When a skill is not called: check the file location first
Translated from Korean. View original
A skill that ‘does not work’ can have several different problems. First distinguish a file that was not found, one that was found but not selected, and execution that stopped partway through. Follow the checks in Claude Code for location, filename, invocation settings and required tools before repeatedly reinstalling.
At which stage did it stop?
If the name is missing from the skill list, check discovery paths and configuration. If explicit invocation works but an ordinary request does not, inspect the description and invocation settings. If an error follows an indication that the skill was read, check its required files and tools.
An incorrect result is a separate problem. If invocation worked but the output ignored the organization criteria, revise the body instructions and examples.
How do I check the file location?
Claude Code project skills use the form .claude/skills/skill-name/SKILL.md. Check that the currently open project is the folder containing that file. Also check whether a downloaded ZIP introduced an extra folder level.
A file may have been saved as SKILL.md.txt, or SKILL.md may have been made a folder. Show extensions in your file browser and check the actual name.
Does explicit invocation work but automatic selection fail?
Read whether the description matches the task you are requesting. A ‘write a report’ skill may not match ‘Find anomalies in this table.’ Include common wording and a specific target in the description.
disable-model-invocation: true prevents Claude from choosing the skill on its own. Check whether explicit user invocation was intended and understand the creator's reason before changing it.
Was the skill read but execution failed?
Check whether the file path in the error can actually be opened. An absolute path from another computer or a missing reference file can stop that step. If the skill requires an executable program, check that it is installed.
If tool access was denied, inspect the required permission. Checking whether the access is needed for the requested task is more useful for finding the cause than opening all permissions at once.
What should I send when asking for help?
Fill in the details below. Remove passwords and personal information from file contents before sharing.
Example: ‘I am using the meeting-note skill in Claude Code. Its path is project/.claude/skills/meeting-note/SKILL.md. Explicit invocation does …, while an ordinary request does …. Version: …. Original error: …. Please determine whether the issue is discovery, automatic selection or execution.’
One line each for the expected and actual result narrows the investigation more than sending an entire screen with ‘It does not work.’
Frequently asked questions
Q. I edited the file but get the same answer. A. Instructions from the existing conversation may still have an effect. Invoke the skill in a new conversation and check that it uses the edited file.
Q. Where do I start for a skill installed as a plugin? A. First check activation and loading errors under Installed and Errors in /plugin.