Claude Skills Not Working? Troubleshooting Guide

Start With the Symptom, Not the Whole Setup

Search intent for claude skills not working is informational and urgent. The fastest fix is to identify the failure mode before editing the skill. A broken skill usually fails in one of four places: location, file structure, trigger wording, or workflow quality.

A Claude Skill can be valid Markdown and still fail if it is invisible to Claude, too vague to select, or missing the files its instructions reference.

1. Check the Skill Location

If Claude never appears to use the skill, check placement first. Personal skills belong where Claude can see them across projects. Project skills belong inside the repo where they apply. Mixing those scopes is the most common reason a skill seems broken after switching folders, repos, or machines.

# Personal skill
~/.claude/skills/code-review/SKILL.md

# Project skill
.claude/skills/release-checklist/SKILL.md

If you are unsure which scope you need, use the Claude Code skills folder guide. A skill stored in the wrong scope is not broken; it is just invisible in the place you expected to use it.

2. Check the File Structure

A skill folder needs a correctly named SKILL.md entrypoint. Case matters in practice because a folder with skill.md, Skill.md, or README.md is easy for humans to understand but unreliable as a skill entrypoint.

Also check supporting files. Multi-file skills often reference examples, templates, scripts, or checklists. If you copied only the Markdown file, Claude may load the instructions but fail to follow the process because the referenced material is gone.

customer-reply-review/
|-- SKILL.md
|-- examples/
|   |-- strong-reply.md
|   `-- weak-reply.md
`-- checklist.md

The complete folder is the skill. Treat SKILL.md as the index, not the entire asset, when the workflow depends on examples.

3. Fix Invalid or Vague Frontmatter

When Claude finds the folder but does not pick the skill at the right time, inspect the frontmatter and description. The description should name the job the skill performs, the situation where it should be used, and the output it produces.

A skill description is a routing signal. If it sounds like a category label, rewrite it into a use condition. For the full format, use SKILL.md explained.

4. Test Invocation With a Narrow Task

After the structure looks right, test the skill with a task that clearly matches its description. Do not ask a broad question like "help me write this." Ask for the exact workflow.

Use the customer reply review skill to improve this draft.
Check tone, missing troubleshooting steps, escalation risk, and the final customer-facing answer.

If Claude follows the expected sequence, the skill is discoverable. If it still gives a generic answer, tighten the skill instructions and add a small example of the desired output.

5. Fix Skills That Work Only on One Computer

Many teams think a skill is broken when it is really stranded. It exists on the old laptop, in one repo, or in one teammate's local folder. The next machine has a partial copy, no version history, or a stale draft.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude, so your setup follows you across every machine, repo, and tool.

If portability is the failure mode, read how to sync Claude Skills across multiple computers and keep the fixed version somewhere durable. For a hands-on rebuild, use the free Claude Skill Creator.

FAQ: Claude Skills Not Working

Why are my Claude Skills not working?

Claude Skills usually stop working because the skill is in the wrong folder, the required SKILL.md file is missing or misnamed, frontmatter is invalid, the description does not match the task, or supporting files were not copied with the skill.

How do I know if Claude loaded my skill?

Ask for the workflow the skill describes and check whether Claude follows the expected process, constraints, examples, and output format. If behavior is generic, verify the folder path, SKILL.md filename, description, and invocation wording.

Can a Claude Skill work in one project but not another?

Yes. A project skill only applies inside the repository where it is installed. If you need the same workflow across projects, install it as a personal skill or manage it in a synced skill library.

Should I recreate a broken Claude Skill from scratch?

Usually no. First check placement, filename, frontmatter, description, supporting files, and whether the skill is too broad. Recreate the skill only after the structure is correct and the workflow itself is unclear.