Diagnostic checklist (start here)
Before diving into specific symptoms, run through this checklist in order. Most issues are caught at step 1 or 2.
- 1 Is the skill installed? Run npx skills list and confirm the skill name appears in the output. If it doesn't, it was never installed or was removed.
- 2 Is the SKILL.md in the right location? Global skills must be at ~/.claude/skills/skill-name/SKILL.md. Project skills must be at .claude/skills/skill-name/SKILL.md relative to your project root.
- 3 Is the frontmatter valid YAML? Open the SKILL.md file and check the block between the --- delimiters. A single missing quote or off-by-one indentation breaks the whole file.
- 4 Does the slash command name match? The name: field in frontmatter is what becomes the slash command. If you installed my-skill but the name: field says myskill, you need to type /myskill, not /my-skill.
- 5 Did you restart Claude after installing? Skills are loaded at session start. If you installed a skill while a Claude Code session was already running, you must start a new session for it to appear.
Skill not appearing in slash commands
If a skill doesn't show up in the / autocomplete, the problem is almost always one of three things: the file doesn't exist at the expected path, the frontmatter is missing the name: field, or the session hasn't been restarted since install.
Verify the file path
For a globally installed skill named frontend-design, confirm the file exists:
# Check the file exists
ls ~/.claude/skills/frontend-design/SKILL.md
# Or list all installed skill folders
ls ~/.claude/skills/
# For a project-level skill (run from your project root)
ls .claude/skills/
If the file is missing, re-run the install command. If it exists, the issue is in the content.
Check for a valid name field
Open the skill's SKILL.md and look at the frontmatter block at the top of the file. It must contain a name: field:
---
name: my-skill
description: Refactors React components to use hooks.
version: 1.0.0
author: "@you"
---
# The rest of the skill instructions follow here...
If the name: field is absent, Claude Code cannot register the slash command and the skill will be silently skipped.
Restart Claude Code
Quit your current Claude Code session entirely and start a new one. Skills are read at session startup — there is no hot-reload mechanism. This applies to both the CLI and IDE extensions.
Skill triggers but Claude ignores instructions
This is the most frustrating failure mode: you invoke the skill, Claude acknowledges it, but then proceeds as if the instructions don't exist. Three causes account for most cases.
The description field is too vague
The description: in frontmatter is used by Claude to understand when to apply the skill's context. A description like Helps with code gives Claude nothing to work with. Write descriptions that are specific about domain, action, and output:
# Too vague — Claude may not apply the skill correctly
description: Helps with code
# Specific — Claude knows when and how to apply this skill
description: Rewrites React class components to functional components
with hooks. Outputs only modified files with no explanatory prose.
The SKILL.md body is too long
Claude has a finite context window. If your SKILL.md is very long (thousands of lines of references, examples, and templates), the actual instructions can be diluted or the file may be truncated before the most important parts. Keep the core instructions at the top of the SKILL.md body, and move large reference material to a separate references/ subfolder that the skill loads on demand.
As a rule of thumb: the actionable instructions in SKILL.md should fit in under 300 lines. Supporting material belongs in skill/references/.
Conflicting instructions from another skill
If you have multiple skills installed that touch the same domain — for example, two different code-style skills — their instructions can contradict each other, and Claude may blend them unpredictably. To test in isolation:
- Temporarily move all other skill folders out of ~/.claude/skills/ except the one you're debugging.
- Start a new Claude Code session.
- Invoke the skill and check whether it behaves correctly.
- Re-add the other skills one by one to identify the conflict.
Once you identify the conflicting pair, rename one skill's name: field or reduce the scope of its description: to avoid overlap. See Global vs. project skills for how scoping can also help isolate conflicts.
Frontmatter errors
The YAML frontmatter block is read by the Skills CLI and by Claude Code. Even a small syntax error silently breaks the skill. These are the most common mistakes.
Common YAML mistakes
---
# Missing quotes around a value with a colon in it — YAML parser error
description: Deploy: push to Netlify and notify Slack
# Extra leading space on an indented list item — indentation must be consistent
tags:
- deploy
- notify
# Trailing space after the closing --- delimiter can cause parse failures
---
name: my-skill
---
---
name: deploy-notify
description: "Deploy: push to Netlify and notify Slack"
version: 1.0.0
author: "@you"
tags:
- deploy
- notify
---
Key rules to remember:
- Wrap values that contain :, #, [, or ] in double quotes.
- List items under a key must use consistent indentation — two spaces is the standard.
- The opening and closing --- delimiters must be on their own lines with no trailing spaces.
- Multi-line values use the | or > YAML block scalar syntax — never a bare newline inside a quoted string.
Skills working locally but not for teammates
Skills installed locally with npx skills add -g live in your home directory and are not shared with anyone else. For a skill to work for the whole team, it needs to be in the project's .claude/skills/ folder and committed to version control.
Commit the skill to the repo
# Install at project scope (no -g flag), from the project root
npx skills add owner/repo@skill-name -y
# Commit the installed skill folder
git add .claude/skills/skill-name/
git commit -m "chore: add skill-name to project skills"
git push
Once committed, any teammate who pulls the branch will have the skill available the next time they open Claude Code in that project — no manual install required.
Teammates need to run npx skills check
If a teammate pulled your changes but the skill still isn't working on their machine, have them run:
npx skills check
This verifies that all skills in .claude/skills/ are intact and registers any new ones with their local Claude Code configuration.
Version mismatch
Skills in .claude/skills/ are pinned to whatever version was installed. If you later update the skill globally on your machine but forget to update the project folder, teammates will run an older version. Always update the committed folder and commit the change when upgrading a team skill.
When to reinstall
If you've worked through the checklist and the skill still misbehaves, a clean reinstall is often the fastest path forward. This is the "nuclear option" — it removes and re-fetches the skill from scratch, discarding any corrupted or partially-written files.
# Remove the existing install, then reinstall fresh
npx skills remove skill-name
npx skills add owner/repo@skill-name -y
# For a global install, add the -g flag
npx skills remove skill-name
npx skills add owner/repo@skill-name -g -y
Use a clean reinstall when:
- The skill file exists but the slash command never appears.
- You manually edited the SKILL.md and the skill started behaving inconsistently.
- The install was interrupted (network drop, Ctrl-C mid-install).
- The upstream skill was updated and you want to pick up the latest version.
Save any local edits first
If you've customized the SKILL.md file locally, npx skills remove will delete those changes permanently. Copy your edits to a safe location before running the remove command.
If reinstalling doesn't resolve the issue, check whether the problem is with the upstream skill itself: browse to the skill's source repository on GitHub and see if other users have reported the same issue in recent commits or open issues.
FAQ
My skill works in Claude Code CLI but not in VS Code. Why?
The VS Code extension reads skills from the same global path (~/.claude/skills/) as the CLI, but the extension needs to be reloaded after a new skill is installed. Run the Developer: Reload Window command in VS Code after installing, or close and reopen the window entirely.
Can two skills conflict with each other?
Yes. If two skills have overlapping trigger descriptions or the same name: field, Claude may load one and silently ignore the other, or blend their instructions unpredictably. To diagnose, temporarily remove all skills except the one you're testing, confirm it works in isolation, then re-add skills one by one to find the conflict. Fix it by making the descriptions more specific or renaming one skill's command.
How do I see what Claude is reading from my skill?
Start a Claude Code session, invoke the skill with its slash command, then immediately ask: "What instructions did you just load from this skill? Summarize them." Claude will echo back what it received. This is the fastest way to confirm the skill content is being read correctly and not truncated.
The skill worked yesterday and broke today — what happened?
The most common cause is a Claude Code update that changed how skills are loaded or scoped. Run npx skills check to verify the install, and npx skills update to pull any upstream fixes from the skill author. If the problem persists, do a clean reinstall: npx skills remove skill-name && npx skills add owner/repo@skill-name -y.