Troubleshooting skills

Skills usually fail due to not triggering, not loading, conflicts, or runtime failures. Many fixes are straightforward.

If a skill doesn't trigger, the description is often the problem. Claude uses semantic matching, so the request needs to overlap with the description's meaning. Add common trigger phrases and test with variations.

If a skill doesn't appear, check its location and structure. The 'skill.md' file must be inside a named directory and use 'skill.md' exactly. Use 'claude-debug' to find loading errors.

If Claude uses the wrong skill or is confused, descriptions are likely too similar. Make them distinct. Also, be aware that enterprise or higher-priority skills with the same name will override personal skills; rename personal skills if necessary.

If a plugin is installed but not visible, clear the cache, restart Claude, and reinstall. If problems persist, the plugin structure might be incorrect, and the validator tool can help.

If a skill loads but fails during execution, ensure external packages are installed and that scripts have execute permissions. Use forward slashes for paths, even on Windows.

A quick checklist for common issues: improve descriptions for triggering, check paths and file names for loading, make descriptions distinct for conflicts, rename shadowed skills, clear cache for missing plugins, and verify dependencies and permissions for runtime failures.