ThisCalculator

Everyday

Claude Code Skill Not Loading? Fix the Description

Updated · Standard formula, shown below

If a Claude Code skill isn’t loading, the cause is almost always a malformed or incomplete SKILL.md file — specifically a missing or incorrect YAML frontmatter description. Fixing it means rewriting the description to be a clear, one-sentence summary, then testing the skill with a direct prompt in a fresh Claude Code session.

What Are Claude Code Skills?

Claude Code skills are folders containing a SKILL.md file plus optional resources (scripts, templates, reference docs). They let you package reusable instructions and tools so Claude can invoke them when relevant to a task. For example, a “commit-message” skill might contain a SKILL.md that describes when to use it and a script that generates conventional commit messages.

The SKILL.md file starts with YAML frontmatter, which includes a name and a description. Claude uses the description to decide whether to load the skill for a given user request. If the description is vague, too long, or missing, the skill may never be triggered.

Why a Skill Fails to Load

The most common reasons a skill doesn’t load are:

  • Missing frontmatter: The --- delimiters are absent, so the entire file is treated as plain text.
  • No description field: The YAML lacks a description key, so Claude has nothing to match against.
  • Description is too long or unfocused: A paragraph of text dilutes the trigger. Claude may not recognize the relevance.
  • Description doesn’t match the prompt: The wording is so specific that a natural user request won’t overlap with it.
  • Skill directory not in the right path: Skills must be in ~/.claude/skills/ (or the project’s .claude/skills/). A wrong folder means Claude never sees it.
  • Syntax errors in YAML: A stray tab or unquoted colon can break parsing.

How to Improve the Description

Write a description that is a single, concrete sentence stating what the skill does and when to use it. Use keywords a user would naturally type. For example:

  • Weak: “This skill helps with writing better commit messages and includes various templates and best practices for teams.”
  • Strong: “Use this skill when writing a git commit message. It generates a conventional commit format (type, scope, subject) and checks it against team rules.”

Keep it under 1024 characters (the documented limit) but aim for one or two sentences. Avoid phrases like “This skill is about…” — instead, use imperative or conditional phrasing that matches how a user asks.

Step-by-Step Fix and Test

  1. Open the SKILL.md file in your skill folder.
  2. Ensure the frontmatter is at the very top, enclosed by --- lines.
  3. Verify the name field matches the folder name (e.g., folder commit-message, name commit-message).
  4. Rewrite the description to a single, specific sentence with trigger keywords.
  5. Save the file and restart Claude Code completely (exit and relaunch).
  6. Test with a direct prompt: /skill commit-message (or the skill’s name). If that works, then test with a natural prompt like “Write a commit message for the changes I just made.”
  7. If it still fails, run /skills to list available skills and confirm yours appears.

Common Mistakes and Misconceptions

A frequent mistake is putting the description on multiple lines without proper YAML quoting. YAML treats a newline as a space, so a multi-line description can become one long run-on sentence that dilutes the trigger. Use a single line or use >- or |- to fold lines correctly.

Another misconception is that skills load automatically for any related task. In reality, Claude decides based on the description and the conversation context. A skill that is too narrow may never be triggered unless the user explicitly asks for it. Conversely, a skill that is too broad may be loaded for unrelated tasks, wasting context.

Also, skills are not plugins — they don’t run code on load. They only provide instructions and files. If your skill relies on a script, the script is executed only when Claude chooses to use it, not when the skill loads.

Testing Your Skill Effectively

Beyond a simple prompt, test the skill in a realistic scenario. Create a small test project, make a change, and ask Claude to perform the task the skill covers. Watch the conversation to see if Claude mentions the skill or uses its files. If it doesn’t, check the debug output by running Claude Code with --debug or --log-level DEBUG to see why the skill wasn’t selected.

You can also add a temporary line to the skill’s instructions like “Start your response with [SKILL LOADED]” to verify it was invoked. Remove that line after testing.

Frequently Asked Questions

How do I know if a skill is loaded?

You can type /skills in Claude Code to see all available skills. If yours appears, it’s recognized. To confirm it’s actually used, ask a prompt that matches the description and see if Claude references the skill’s instructions or files in its response.

Can I load a skill manually?

Yes, you can force-load a skill by typing /skill skill-name in the Claude Code prompt. This bypasses the automatic selection process and is a good way to test the skill itself.

What if the skill still doesn’t load after fixing the description?

Check the folder path and permissions. The skill must be in ~/.claude/skills/ (global) or .claude/skills/ in your project root. Ensure the folder name matches the name field exactly, and that the file is named SKILL.md (case-sensitive on Linux/macOS).

Does the description need to include every possible trigger phrase?

No. A single, well-written sentence with a few key synonyms is enough. Overloading it with keywords can make it less effective. Focus on the core task and the most natural phrasing.

Can I have multiple skills with similar descriptions?

Yes, but Claude may pick the first one it finds. To avoid ambiguity, make each description distinct, or use the name field in the prompt to force the right one.

Is there a limit to the description length?

Anthropic’s documentation suggests keeping descriptions under 1024 characters. In practice, shorter (under 200 characters) works best for precise triggering.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.