Notes
Claude
Introduction to Agent Skills
Troubleshooting Skills

Troubleshooting Skills

Note

TL;DR

  • Start with the skills validator tool — it catches structural problems before you spend time debugging other things
  • If a skill doesn’t trigger, the cause is almost always the description — add trigger phrases that match how you actually phrase requests
  • If a skill doesn’t load, check that SKILL.md is inside a named directory (not at the skills root) and the file name is exactly SKILL.md
  • If the wrong skill gets used, your descriptions are too similar — make them more distinct
  • For runtime errors, check dependencies, file permissions (chmod +x), and path separators (use forward slashes everywhere)

Use the Skills Validator

The first thing to try is the agent skills verifier command.

Installation steps vary by operating system, but using uv is the easiest way to get it set up quickly.

Once installed, either navigate to your skill directory or run the command from anywhere. The validator will catch structural problems before you spend time debugging other things.

The Problems

When skills don’t work, the problem usually falls into one of a few categories: the skill

  • doesn’t trigger,
  • doesn’t load,
  • has conflicts, or
  • fails at runtime.

Quick troubleshooting checklist:

  • Not triggering? -> Improve your description and add trigger phrases.
  • Not loading? -> Check your path, file name, and YAML syntax.
  • Wrong skill used? -> Make descriptions more distinct from each other.
  • Being shadowed? -> Check the priority hierarchy and rename if needed.
  • Plugin skills missing? -> Clear cache and reinstall.
  • Runtime failure? -> Check dependencies, permissions, and paths.

Skill doesn’t trigger

Problem: Your skill exists and passes validation, but Claude isn’t using it when you expect.

Root cause: The description. Claude uses semantic matching, so your request needs to overlap with the description’s meaning. If there’s not enough overlap, no match.

Fix:

  • Check your description against how you’re actually phrasing requests
  • Add trigger phrases users would actually say
  • Test with variations like “help me profile this,” “why is this slow?”, “make this faster”
  • If any variation fails to trigger, add those keywords to your description

Skill doesn’t load

Problem: The skill doesn’t appear when you ask Claude “what skills are available”.

Fix:

  • Check these structural requirements:
    • The SKILL.md file must be inside a named directory, not at the skills root
    • The file name must be exactly SKILL.md — all caps on “SKILL”, lowercase “md”
  • Run claude --debug to see loading errors. Look for messages mentioning your skill name.

Wrong skill gets used

Problem: Claude uses the wrong skill or seems confused between skills

Root cause: Your descriptions are probably too similar.

Fix: Make them distinct.

  • Being as specific as possible doesn’t just help Claude decide when to use your skill — it also prevents conflicts with other similar-sounding skills.

Skill priority conflicts

Problem: Your personal skill is being ignored,

Root cause: An enterprise or higher-priority skill might have the same name.

Fix:

  • Rename your skill to something more distinct (this is usually the easier path)
  • Talk to your admin about the enterprise skill

Plugin skills not appearing

Problem: Installed a plugin but can’t see its skills.

Fix:

  • Clear the cache, restart Claude Code, and reinstall.
  • If skills still don’t appear after that, the plugin structure might be wrong. -> Use the validator tool.

Runtime errors

Problem: The skill loads but fails during execution.

Root CauseFix
Missing dependenciesIf your skill uses external packages, they must be installed. Add dependency info to your skill description so Claude knows what’s needed.
Permission issuesScripts need execute permission. Run chmod +x on any scripts your skill references.
Path separatorsUse forward slashes everywhere, even on Windows.
docs