Claude Code Skills Not Loading? Common Fixes

You installed a skill from the mdskills.ai marketplace. It shows up in your config. But Claude Code pretends it doesn't exist.

This happens more than you'd think. The problem isn't usually the skill itself but how Claude Code loads and processes skills. Here's what breaks and how to fix it.

Restart Claude Code completely

The most boring fix works 40% of the time. Claude Code doesn't hot-reload skills. It reads your configuration once at startup, then ignores changes until you restart.

Close Claude Code entirely. Not just the window. Check your task manager and kill any lingering processes. Then relaunch.

If the skill loads now, you're done. If not, keep reading.

Check the file structure

Skills need specific files in specific places. Claude Code is picky about this.

Your skill directory should look like this:

my-skill/
├── SKILL.md
├── CLAUDE.md (optional but recommended)
└── any other files

The SKILL.md spec defines what goes inside. But the filename matters too. Not skill.md or Skill.md. Exactly SKILL.md in caps.

Same with CLAUDE.md if you're using it. The CLAUDE.md spec is case-sensitive.

Verify the SKILL.md format

Open your SKILL.md file. The first few lines should look like this:

# Skill Name

Brief description of what this skill does.

## Usage

How to use the skill...

No YAML frontmatter. No weird markdown extensions. Just clean, standard markdown starting with an H1.

If you copied a skill from somewhere else, it might have extra formatting that breaks the parser. Strip it down to basics.

Look for syntax errors in CLAUDE.md

The CLAUDE.md file tells Claude Code how to use your skill. Bad syntax here breaks everything silently.

Check for:

Unclosed code blocks (missing closing ```)
Invalid XML in examples
Broken function signatures
Malformed tool definitions

Claude Code doesn't give helpful error messages for these. It just ignores the whole skill.

Check the installation path

Skills must live in the right directory. The exact location depends on your setup, but it's usually:

~/.claude-code/skills/your-skill-name/

If you put the skill somewhere else, Claude Code won't find it. The install skills guide covers the correct paths for each platform.

Some users try to organize skills into subdirectories like ~/.claude-code/skills/web/my-skill/. This breaks loading. Keep skills flat in the main skills directory.

Test with a minimal skill

Create a dead-simple test skill to isolate the problem:

# Test Skill

This skill does nothing but proves loading works.

## Usage

Just say "test skill" and I'll respond.

Save this as SKILL.md in a new directory called test-skill. If this loads but your original skill doesn't, the problem is in your skill's content, not the system.

Watch for permission issues

On macOS and Linux, file permissions can block Claude Code from reading your skills. The skills directory and all files inside need read permissions for your user.

chmod -R 644 ~/.claude-code/skills/
chmod 755 ~/.claude-code/skills/*/

This sets files to read-only and directories to executable, which is what Claude Code expects.

Clear the skill cache

Claude Code caches skill metadata to speed up loading. Sometimes this cache gets corrupted.

The cache lives in a platform-specific location:

# macOS
~/Library/Application Support/Claude Code/skill-cache/

# Linux
~/.config/claude-code/skill-cache/

# Windows
%APPDATA%/Claude Code/skill-cache/

Delete everything in that directory. Claude Code will rebuild it on next startup.

Check for conflicting skills

If you have multiple skills with the same name or overlapping functionality, Claude Code might load the wrong one or get confused.

List your installed skills:

ls ~/.claude-code/skills/

Look for duplicates or skills with very similar names. Rename or remove conflicts.

This is different from MCP servers, which have their own namespace. Skills share a global namespace within Claude Code.

Enable debug logging

Claude Code has hidden debug options that show what's happening during skill loading.

Add this to your Claude Code settings:

{
  "debug": {
    "skillLoading": true
  }
}

Restart Claude Code and check the console output. You'll see exactly which skills load successfully and which fail.

The logs usually reveal the specific error: missing files, syntax problems, or permission issues.

When skills load but don't work

Sometimes Claude Code loads your skill successfully but doesn't use it in conversations. This is a different problem.

Check if your skill instructions are clear enough. Vague descriptions like "helps with coding" don't give Claude enough context. Be specific about when and how to use the skill.

Compare your skill to the skill best practices guide. Good skills have clear triggers, concrete examples, and focused functionality.

Try a known working skill

Download a skill from the browse skills page that has good ratings. If marketplace skills work but yours don't, the issue is in your skill's implementation.

Start with something simple like a code formatter or documentation generator. These have straightforward requirements and fewer moving parts.

Still broken?

If none of these fixes work, the problem might be deeper. Check the Claude Code GitHub issues for known bugs affecting skill loading. Sometimes specific versions have breaking changes.

You can also compare your approach to skills vs MCP to see if a different solution fits better. MCP servers handle some use cases more reliably than skills.

The debugging process teaches you how Claude Code actually works with skills. That knowledge helps when creating your own skills or troubleshooting future issues.