Transcript of Troubleshooting skills
Claude
0:03When skills don't work, the problem0:05usually falls into one of a few0:07categories.0:09The skill doesn't trigger,0:11doesn't load,0:12has conflicts, or fails at runtime.0:15But, [music]0:16good news.0:17Most fixes are pretty straightforward.0:19Here's some of them.0:22First thing we can do is try the agent0:23skills verifier command.0:26Depending on your operating system,0:28installation steps will differ. But, we0:30recommend using UV as it's the easiest0:32way to get it installed fast.0:35Once installed, either navigate to your0:36skill directory or run this command from0:38anywhere.0:41Your skill exists, it passes the0:43validator, but Claude isn't using it0:46when expected.0:47Hmm.0:48Well, the cause is almost always the0:50description. Claude uses semantic0:53matching, so your request needs to0:54overlap with the description's meaning.0:57If there's not enough overlap,1:00no match. Check your description against1:02how you're phrasing requests. Add1:04trigger phrases users would actually1:06say. Test with variations. Help me1:09profile this. Why is this slow? Make1:12this faster. If any fail to trigger, add1:14those keywords to your description.1:16If your skill doesn't appear when you1:18ask Claude, what skills are available?1:21Well, check these things. Skills must be1:23in the right location with the right1:24structure. The skill.md file must be1:27inside of a named directory, not at the1:29skills root. The file name must be1:31exactly skill.1:33md, all caps on the skill. Lowercase md.1:37Just crossing things off the list here,1:38okay? Just crossing them off.1:40Run Claude --debug to see loading1:43errors. Look for messages mentioning1:45your skill name.1:46Sometimes this will just solve the1:48problem for you.1:50If Claude uses the wrong skill or seems1:53confused, your descriptions are probably1:55too similar.1:57Make them distinct. Remember, being as1:59specific as possible doesn't just help2:01with Claude deciding when to use your2:03skill, but not conflicting with other2:05similar-sounding skills.2:07If your personal skill is being ignored,2:09an enterprise or higher priority skill2:12might have the same name, so investigate2:14that. If you see an enterprise code2:17review, and you also have a personal2:19code review, well, the enterprise one2:22will win every time. So, your solution2:25is to rename your skill to something a2:26little bit more distinct. Talk to your2:28admin about the enterprise skill, but2:31you'll have a better chance with number2:32one, probably.2:35Install the plugin, but can't see its2:37skills? Well, clear the cache. Restart2:40Claude Code and reinstall. If skills2:42still don't appear, the plugin structure2:44just might be wrong. This is when the2:46validator tool makes sense.2:49The skill loads, but fails during2:50execution. If your skill uses external2:53packages, they must be installed. Add2:55this info to your description.2:58Scripts need execute permission. Use3:01forward slashes everywhere, even on3:02Windows.3:06So, here's a quick checklist. Not3:08triggering? Well, improve your3:10description and trigger phrases. Not3:12loading? Check your path, file name,3:14YAML syntax. Wrong skill used? [music]3:17Make your descriptions a little bit more3:18distinct. Are you being shadowed? Check3:21the priority and rename if needed.3:24Plugins are missing?3:25Clear your cache and reinstall. Runtime3:28failure? Check dependencies,3:29permissions, and paths.
517 words · 96 lines
