Skip to main content
Troubleshooting

Claude Skills Not Working? Nine Checks to Run

Fix Claude skills that do not show up or trigger: check Code paths, live reload, invocation settings, and the different setup for Claude chat and Cowork.

Updated October 2, 2026 · 7 min read

Start by identifying where the skill should run: a local Claude Code session, Claude chat, or Cowork in the Desktop app. Their installation and discovery steps differ. Then separate a missing skill from one that is available but does not trigger. If you are still setting it up, the guide to creating a skill describes the full format.

1. Check the file name and folder layout

The file must be named SKILL.md — uppercase, exactly. Not skill.md, not Skill.MD, not SKILLS.md. It also has to live inside its own named folder:

~/.claude/skills/
└── excel-reports/
    └── SKILL.md      ✅ correct

~/.claude/skills/SKILL.md   ❌ loose file, ignored

2. Confirm you used the right directory

For local Claude Code skills, these are the usual personal and project locations:

  • ~/.claude/skills/ — personal skills, available in every project.
  • .claude/skills/ (at your project root) — project skills, committed with the repo.

Check which repository your Code session is using. Plugins and managed skills have other locations; these two folders are not an exhaustive list. For Claude chat or Cowork in the Desktop app, upload and enable skills in Customize > Skills. Copying a folder into ~/.claude/skills/ is not a Desktop install.

3. Check discovery and reload when needed

Current Claude Code watches skill directories and picks up SKILL.md changes during the session, except in bare mode. If you created a top-level skills directory after the session started, run /reload-skills; repeat it after later changes in that directory. Plugin hooks and configuration changes require /reload-plugins. See the official live reload guidance for the exact scope.

4. Make the description match the task

If the skill is available but does not trigger, inspect the description alongside the invocation settings in step 6. Describe the job and the situations in which the skill should be used. Compare:

Vague descriptionMore specific description to test
description: Helps with spreadsheetsdescription: Create formatted .xlsx spreadsheets with formulas and charts. Use when the user asks for an Excel file, a spreadsheet, or a financial model.

State what the skill does and when to use it, in the third person, and include the words users actually type. The Skill Creator writes these for you if you are unsure.

5. Keep the frontmatter valid

The YAML block at the top must be well-formed: opening and closing --- lines, valid keys, and spaces for indentation. Quote values containing YAML punctuation where necessary. Check the actual parser error or startup warning before assuming the model ignored valid instructions. Keep the description concise and move detailed procedures into the body.

6. Confirm that the skill is enabled

In Code, disable-model-invocation: true prevents automatic use, whileuser-invocable: false prevents manual invocation. Check plugin activation if the skill came from a plugin. In Claude chat or Cowork, confirm that the skill and code execution are enabled; organization settings can also restrict them. Follow the Claude skills setup instructions for your account.

7. Clear the permissions / temp blocker

If the skill loads but a bundled script fails, read that script’s error. Check required dependencies, file paths, and the permissions for its working directory. Only grant the access the task needs; a script execution failure is a different problem from skill discovery.

8. Try invoking it explicitly

To isolate whether the problem is discovery or triggering, invoke the skill by name (e.g. /excel-reports in Claude Code), provided manual invocation is enabled. If that works but automatic use does not, revisit both the description and invocation controls.

9. Update Claude and check the changelog

Check the app version before applying current instructions to an older installation. Use the Claude Code troubleshooting reference to compare behavior. Update if the feature you need requires a newer release, then test the same request again.

Still stuck?

Rebuild the skill from a known-good template using the Skill Creator, or study a well-structured official skill like the PDF skill or MCP Builder and mirror its frontmatter. When in doubt, start from something that already works and change one thing at a time.

Frequently asked questions

Why is my Claude skill not triggering?

First check whether the skill is available in the app you are using. In Claude Code, try /skill-name if the skill allows manual invocation. If it is available but does not trigger automatically, check its description and disable-model-invocation setting. In Claude chat or Cowork, check that the skill is enabled in Customize > Skills.

Where do skills go in Claude Code?

Personal skills that should work in every project go in ~/.claude/skills/<skill-name>/SKILL.md. Project skills that ship with a repo go in .claude/skills/<skill-name>/SKILL.md at the project root. The file must be named SKILL.md exactly (uppercase), inside its own named folder.

Do I need to restart Claude after adding a skill?

Not normally in current Claude Code: watched skill directories pick up SKILL.md changes during the session. If the top-level skills directory did not exist at startup, run /reload-skills after creating it and after later changes there. Bare mode does not watch skill directories. Claude chat and Cowork use account-managed skills instead of this local-folder workflow.

Why does my skill work sometimes but not always?

Compare the app, project, available skills, and invocation settings between sessions. If the same skill is available each time, make its description specific about the task and test a few representative requests. A successful manual invocation alone does not guarantee automatic triggering.

Skills that illustrate the format

Analysis & Researchintermediate

Skill Creator

Scaffold a new AI agent skill from a plain-language job description: folder, SKILL.md frontmatter, trigger description, and a first draft of...

76OpxScoreProvisional

Model fit

ClaudeChatGPTGemini+5
197.7K65
View
Coding & Developmentintermediate

Mcp Builder

Design and implement Model Context Protocol servers so an agent can call external tools with typed schemas instead of stuffing API docs into...

67OpxScoreProvisional

Model fit

Model fit pending
197.7K66
View
Productivity & Workflowintermediate

Webapp Testing

Use Python Playwright to test local web applications, inspect visible UI behavior, capture screenshots, and collect browser logs.

81OpxScoreProvisional

Model fit

Model fit pending
197.7K63
View
Creativity & Designintermediate

Doc Coauthoring

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical s...

57OpxScoreProvisional

Model fit

Claude
197.7K56
View

Browse all skills in the directory →

More guides

Weekly digest

Receive published digests of new listings and catalogue updates. Confirm your email to join.

Double opt-in required. You may unsubscribe at any time.