Skills Not Working? Troubleshooting SKILL.md Loading Issues
Your skills aren't loading and Claude Code is acting like they don't exist. The issue usually comes down to three culprits: file naming mistakes, broken frontmatter, or path problems that prevent the AI from finding your SKILL.md files.
File naming breaks everything first
The filename must be exactly SKILL.md with all caps. Not skill.md, not Skill.md, not skills.md. Case sensitivity matters more than you'd expect.
# Wrong
touch skill.md
touch Skills.md
touch SKILLS.md
# Right
touch SKILL.md
Some developers create multiple skill files and wonder why only one loads. Each directory can only contain one SKILL.md file. If you need multiple skills, put them in separate directories.
The same rule applies to related files. Rules files must be named RULES.md exactly, and CLAUDE.md spec files follow the same pattern.
Frontmatter syntax errors kill loading
YAML frontmatter sits at the top of every SKILL.md file between triple dashes. One syntax error breaks the entire file.
---
name: "Data Analysis"
description: "Analyze CSV files and generate reports"
author: "Your Name"
version: "1.0.0"
tags: ["data", "analysis", "csv"]
---
Missing quotes around strings cause silent failures. The parser expects quoted values for name and description fields. Tags must be an array, even for single items.
Indentation matters in YAML. Use spaces, not tabs. Two spaces per indent level works reliably.
# Breaks silently
---
name: Data Analysis
description: Analyze CSV files
tags: data
---
# Works correctly
---
name: "Data Analysis"
description: "Analyze CSV files"
tags: ["data"]
---
Check your frontmatter in a YAML validator before assuming the skill logic is broken. Bad YAML means the file never gets parsed.
Path issues prevent skill discovery
Claude Code looks for SKILL.md files in specific locations. If your file sits in the wrong directory, it won't load.
Skills live in your project's skill directories. Create a skills folder in your project root and put each skill in its own subdirectory.
project/
├── skills/
│ ├── data-analysis/
│ │ └── SKILL.md
│ └── file-processing/
│ └── SKILL.md
└── main.py
Some tools expect skills in a .skills hidden directory instead. Check your tool's documentation for the exact path requirements.
Relative paths in your SKILL.md content can cause loading issues too. Use absolute paths or paths relative to the skill directory, not your project root.
The install skills process varies between tools, so double-check you're following the right steps for your environment.
Markdown formatting problems
The content after frontmatter must be valid Markdown. Broken formatting doesn't stop loading but makes skills unusable.
Code blocks need proper language identifiers. Unmatched backticks break parsing. Headers should follow a logical hierarchy.
## Usage
This skill processes CSV files.
```python
import pandas as pd
df = pd.read_csv("data.csv")
Results appear in the terminal.
That example shows proper code block formatting with language tags and matched backticks.
## Permission and file system issues
File permissions can prevent loading even when everything else looks correct. Your AI tool needs read access to SKILL.md files.
```bash
# Check permissions
ls -la skills/*/SKILL.md
# Fix if needed
chmod 644 skills/*/SKILL.md
Some systems block execution from certain directories. Try moving your skills folder to a different location if permissions look correct but loading still fails.
Windows users often hit path length limits or special character issues. Keep skill directory names short and avoid spaces or special characters.
Validation and debugging steps
Start with basic file validation. Your SKILL.md should load in any Markdown viewer. If it doesn't render properly, fix the Markdown before troubleshooting the AI integration.
Test frontmatter separately using an online YAML parser. Copy just the frontmatter section and validate it independently.
Check your tool's logs for specific error messages. Most AI coding tools provide debug output when skill loading fails.
# Example debug output locations
~/.cursor/logs/
~/.claude/debug.log
./codex-cli-debug.txt
Create a minimal test skill to isolate the problem. Use the simplest possible SKILL.md with basic frontmatter and one instruction.
---
name: "Test Skill"
description: "Simple test"
author: "Test"
version: "1.0.0"
tags: ["test"]
---
## Instructions
Say "test skill loaded" when activated.
If the minimal skill loads but your complex one doesn't, the issue sits in your content, not the setup.
Understanding what are skills? helps debug loading issues because you'll know what the parser expects to find.
Tool-specific troubleshooting
Each AI coding tool handles skill loading differently. Claude Code expects skills in the project workspace. Cursor looks in specific configuration directories. Codex CLI uses command-line flags to specify skill paths.
Some tools cache loaded skills. Clear the cache when testing fixes:
# Clear tool caches
rm -rf ~/.cursor/skill-cache
rm -rf ~/.claude/cache
codex-cli --clear-cache
Version mismatches between your tool and the SKILL.md spec cause compatibility issues. Check if you're using the latest spec version.
The skills vs MCP comparison explains when to use each approach. If skills keep failing, MCP servers might be a better fit for your use case.
Recovery and prevention
Keep working SKILL.md files as templates. Copy a known-good file when creating new skills to avoid repeated syntax errors.
Version control your skills directory. Git tracks when changes break loading so you can revert quickly.
cd skills
git init
git add .
git commit -m "Working skills baseline"
Regular validation prevents most loading issues. Run your SKILL.md files through formatters and validators as part of your development workflow.
Follow best practices for skill structure. Consistent organization makes troubleshooting easier when problems arise.
Browse working examples in the skills marketplace to see correct formatting and structure. Real skills from other developers show patterns that work reliably.
Most skill loading failures trace back to simple syntax errors or file placement issues. Fix the basics before diving into complex debugging. Your skills will load once the fundamentals are right.
