Troubleshooting skills

• Skills for AI agents can fail to trigger, load, conflict with others, or crash during execution, but most issues have straightforward solutions.
• Effective troubleshooting involves verifying skill structure, refining descriptions for semantic matching, and leveraging debugging tools.
• Common problems stem from inadequate descriptions, incorrect file paths, conflicts with higher-priority skills, or missing dependencies.

• Use the agent skills verifier command to validate the structure and integrity of your skill installation.
• Refine skill descriptions to ensure strong semantic matching with user requests, adding specific trigger phrases users are likely to say.
• Verify that skill files are correctly structured: skill.md must be inside a named directory, not at the skills root, with the exact filename skill.md (case-sensitive for "skill").
• Run claude-debug to identify specific loading errors and messages related to your skill.
• Ensure skill descriptions are distinct to prevent Claude from using the wrong skill or confusing similar ones.
• If a personal skill is ignored, check for an enterprise skill with the same name, as enterprise skills typically take precedence; rename your personal skill if necessary.
• For missing plugins, clear the cache, restart Claude, and reinstall; if problems persist, use the validator tool to check the plugin structure.
• Address runtime failures by ensuring all external packages are installed, scripts have execute permission, and all file paths use forward slashes consistently.

agent skills verifier — A command-line tool used to check the structural validity and installation correctness of an AI agent's skill. semantic matching — The process by which an AI system understands the meaning and intent of a user's request and matches it to relevant skills, rather than just keyword matching. trigger phrases — Specific words or short sentences that, when used by a user, are intended to activate a particular skill. skill.md — The exact filename and extension required for the primary markdown file describing an AI agent's skill. claude-debug — A debugging tool or command specific to the Claude AI environment, used to diagnose issues, particularly loading errors, with skills. enterprise skill — A skill provided or managed by an organization (enterprise) that may have higher priority or specific access controls compared to personal skills. runtime failure — An error that occurs while a skill or program is actively executing, often due to issues like missing dependencies or incorrect permissions. execute permission — A file system permission that allows a user or process to run a script or program. YAML syntax — The specific rules for writing files in YAML (YAML Ain't Markup Language) format, often used for configuration and data serialization in software projects.

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. But [music] good news, most fixes are pretty straightforward. Here are some of them. First thing we can do is try the agent skills verifier command. Depending on your operating system, installation steps will differ, but we recommend using UV as it's the easiest way to get it installed fast. Once installed, either navigate to your skill directory or run this command from anywhere. Your skill exists, it passes the validator, but Claude isn't using it when expected. H well, the cause is almost always 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. Check your description against how you're phrasing requests. Add trigger phrases users would actually say, test with variations. Help me profile this. Why is this slow? Make this faster. If any fail to trigger, add those keywords to your description. If your skill doesn't appear when you ask Claude what skills are available, well, check these things. Skills must be in the right location with the right structure. The skill.md file must be inside of a name directory, not at a skills root. The file name must be exactly skill.md. All caps on the skill lowerase MD. Just crossing things off the list here. Okay, just crossing them off. Run claude-debug to see loading errors. Look for messages mentioning your skill name. Sometimes this will just solve the problem for you. If Claude uses the wrong skill or seems confused, your descriptions are probably too similar. Make them distinct. Remember, being as specific as possible doesn't just help with Claude deciding when to use your skill, but not conflicting with other similar sounding skills. If your personal skill is being ignored, an enterprise or higher priority skill might have the same name. So investigate that. If you see an enterprise code review and you also have a personal code review, well the enterprise one will win every time. So your solutions is to rename your skill to something a little bit more distinct. Talk to your admin about the enterprise skill, but you'll have a better chance with number one. Probably install the plugin but can't see it. Skills? Well, clear the cache. Restart claw code and reinstall. If skills still don't appear, the plug-in structure just might be wrong. This is when the validator tool makes sense. The skill loads but fails during execution. If your skill uses external packages, they must be installed. Add this info to your description. Scripts need execute permission. Use for slashes everywhere, even on Windows. So, here's a quick checklist. Not triggering? Well, improve your description and trigger phrases. Not loading? Check your path, file name, YAML syntax. Wrong skill [music] used? Make your descriptions a little bit more distinct. Are you being shadowed? Check the priority and rename if needed. Plugins are missing. Clear your cache and reinstall. Runtime failure? Check dependencies, permissions, and pass.