SKILL.md Skills Not Loading? Troubleshooting Guide

You installed a skill but your AI agent isn't using it. This guide covers the most common reasons skills fail to load and how to fix each one, across Claude Code, OpenClaw, Codex CLI, Cursor, and other SKILL.md-compatible agents.

Quick Answer: The most common causes: wrong directory path, double-nested folders after unzipping, missing or misnamed SKILL.md file, not starting a new session after install, or a vague description that doesn't match your prompts. Check these in order — one of them is almost always the fix.

Is the skill in the right directory?

This is the #1 cause. Each agent reads from a specific path:

Verify your skill is in the correct directory for your agent:

# For Claude Code
ls ~/.claude/skills/your-skill-name/SKILL.md

# For OpenClaw
ls ~/.openclaw/skills/your-skill-name/SKILL.md

If the file doesn't exist at that path, move it there.

Is the folder structure correct?

The second most common issue. After unzipping, you should have:

~/.claude/skills/code-reviewer/SKILL.md     ← correct

Not:

~/.claude/skills/code-reviewer/code-reviewer/SKILL.md     ← wrong (double-nested)
~/.claude/skills/SKILL.md                                  ← wrong (no skill folder)
~/.claude/skills/code-reviewer/skill.md                    ← wrong (lowercase)

The file must be named exactly SKILL.md (uppercase). On Linux and macOS, filenames are case-sensitive. On Windows (WSL), they may or may not be depending on your filesystem configuration.

Fix a double-nested folder:

mv ~/.claude/skills/code-reviewer/code-reviewer/* ~/.claude/skills/code-reviewer/
rmdir ~/.claude/skills/code-reviewer/code-reviewer

Did you start a new session?

Skills load at session startup. If you installed a skill while a session was running, the agent doesn't know about it yet.

Close your current session and start a new one. For terminal-based agents (Claude Code, OpenClaw, Codex CLI), exit and re-run the agent command. For Cursor, reload the window (Cmd/Ctrl+Shift+P → "Developer: Reload Window").

Is the skill description triggering correctly?

Skills activate when your request matches the skill's description. If the description is too vague or too specific, it won't trigger.

Check the description in your SKILL.md frontmatter:

---
name: code-reviewer
description: Use when the user asks to review code, find bugs, or check for security issues.
---

Too vague: "A helpful coding skill" — the agent can't match this to any specific request.

Too specific: "Use when reviewing TypeScript React components in a Next.js 14 app" — won't trigger for anything else.

Just right: "Use when the user asks to review code, find bugs, check for security issues, or do a PR review" — clear triggers, multiple matching phrases.

If the skill exists and loads but never activates, rewrite the description to include the exact phrases you use when requesting that task. For more detail, read How to Write a SKILL.md Description That Triggers.

Skip the troubleshooting.

Agensi Pro loads skills via MCP — no directories, no file management, no path issues. Your agent pulls the right skill on demand.

Start 3-day free trial →

$9/mo after trial. Card required. Cancel anytime.

Is there a YAML frontmatter error?

Invalid YAML breaks skill loading silently. Common mistakes:

# WRONG — missing closing ---
---
name: my-skill
description: Does things

# Instructions here...

# WRONG — description contains unescaped colon
---
name: my-skill
description: Use for: code review and testing
---

# CORRECT
---
name: my-skill
description: "Use for: code review and testing"
---

If your description contains colons, quotes, or special characters, wrap it in double quotes. The --- delimiters must appear on their own lines with no leading spaces.

Are two skills conflicting?

If you have multiple skills with overlapping descriptions, the agent might load the wrong one. Check if another skill has a description that could match your request:

# List all skill descriptions
for dir in ~/.claude/skills/*/; do
  echo "=== $(basename $dir) ==="
  head -5 "$dir/SKILL.md" | grep "description:"
done

If two skills compete for the same trigger, either make their descriptions more specific or remove the one you don't want.

Is the SKILL.md file actually readable?

Occasionally files get corrupted during download or transfer. Check that the file is valid UTF-8 text:

file ~/.claude/skills/code-reviewer/SKILL.md
# Should output: "UTF-8 Unicode text" or "ASCII text"
# If it says "data" or "binary", the file is corrupted — re-download it

Still not working?

If you've checked all of the above and the skill still doesn't load:

1. Try invoking the skill manually by name (e.g., /code-reviewer in Claude Code)
2. If manual invocation works but auto-discovery doesn't, the description needs rewriting
3. If manual invocation also fails, the skill isn't being detected at all — re-check the directory path
4. As a last resort, delete the skill folder and reinstall from scratch

For agent-specific troubleshooting, read the installation guide for your agent: Claude Code, OpenClaw, or Codex CLI.

---

Browse security-scanned skills that install cleanly on Agensi.