Troubleshooting Guide
Solutions to common skill problems across all platforms
Quick Diagnosis
Most skill issues fall into one of these categories. Find your symptom below and follow the solution.
Skills Won't Trigger
You've installed a skill but Claude doesn't seem to use it
Cause
The skill's description isn't clear enough for Claude to know when to use it. Vague descriptions like "helps with code" prevent proper routing.
Solution
- Open the skill's SKILL.md file and read the first paragraph
- Check if it clearly states what the skill does and when to use it
- Look for skills with higher quality scores (green badges) - they have better descriptions
- Try explicitly mentioning the skill's topic in your prompt to Claude
Pro Tip: The first paragraph of SKILL.md matters more than anything else. Good skills clearly state what they do and what they don't do.
Code Execution Disabled
Skills aren't working at all, or you see warnings about code execution
Cause
Code Execution is disabled in your AI assistant's settings. This is the #1 most common problem.
Solution
For Claude Desktop:
- Open Claude Desktop
- Go to Settings (gear icon)
- Click on "Features"
- Enable "Code Execution"
- Restart Claude Desktop
For Claude Code:
- Code execution is enabled by default in Claude Code
- If skills still don't work, check your configuration file
Skill Not Found After Installation
You installed the skill but it doesn't appear in your skills list
Cause
The skill wasn't placed in the correct directory, or the application wasn't restarted.
Solution
Verify correct location:
~/.claude/skills/[skill-name]/
The skill should be in its own folder inside the skills directory
Check file structure:
~/.claude/skills/
└── my-skill/
├── SKILL.md (required)
├── README.md (optional)
└── ...other files Restart the application:
Claude Desktop and most applications need to be fully restarted to detect new skills
Wrong Skill Gets Triggered
Claude uses a different skill than the one you want
Cause
Multiple skills have overlapping descriptions or handle similar tasks. "Mega-skills" that do too many things confuse the router.
Solution
- Remove or disable skills you're not actively using
- Be more specific in your prompts - mention exactly what you want
- Choose specialized skills over general-purpose ones
- Check skill descriptions for overlap - remove duplicates
Permission or File Access Errors
Errors about file permissions or unable to write files
Cause
The skills directory doesn't have proper permissions, or was created with the wrong user.
Solution
Run these commands in your terminal:
# Make sure the directory exists
mkdir -p ~/.claude/skills
# Fix permissions
chmod 755 ~/.claude/skills
chmod -R 644 ~/.claude/skills/*
Can't Share Skills with Team
Skills work for you but teammates can't use them
Cause
No centralized "push to everyone" mechanism exists. Each user must install skills individually.
Solution
- Share the skill's GitHub repository URL or SkillzWave link with your team
- Create a shared documentation page with installation instructions
- For Claude Code users: Use the Skilz CLI to maintain consistent installations
- Consider using a shared Git repository for your team's custom skills