Claude Skill Not Loading
There are two different failures and they need different fixes:
- Not discovered — the agent doesn't know the skill exists
- Not activated — it knows, but decides it isn't relevant
Start by asking the agent to list its skills. If yours isn't there, it's discovery. If it is, it's the description.
1. Folder depth (discovery)
The file must sit directly inside the skill folder:
.claude/skills/og-image/SKILL.md ✅
.claude/skills/og-image/og-image/SKILL.md ❌
.claude/skills/SKILL.md ❌ (no named folder)Unzipping often creates the extra level. Open the folder and look.
2. Description match (activation)
The model selects skills from the description field alone. If your description is "design helper", a request to "make an OG image" won't match it.
Fix: include the words users actually type.
description: Create 1200x630 OG images and social cards from a title and
optional screenshot. Use when the user asks for an OG image, link preview,
social card, or Twitter card.3. YAML that doesn't parse
A stray tab, an unquoted colon, or a missing --- silently breaks the frontmatter. Paste the block into any YAML validator. If name or description is missing, the skill is invalid.
4. Wrong scope
Project skills live in that repo only. If you installed into .claude/skills inside repo A and you're working in repo B, it isn't there. Global is ~/.claude/skills.
5. Two skills fighting
If two skills have overlapping descriptions, the agent picks one — often not the one you wanted. Narrow both: one owns "OG image", the other owns "YouTube thumbnail".
The 60-second diagnostic
| Check | Command / action |
|---|---|
| Discovered? | Ask the agent to list skills |
| Depth | ls .claude/skills/<name>/ shows SKILL.md |
| YAML | Paste frontmatter into a validator |
| Scope | ls ~/.claude/skills vs project folder |
| Conflict | Search other skills for the same trigger words |
Still stuck?
Read the file the agent reads. If the instructions reference references/layouts.md and that file doesn't exist, behaviour becomes unpredictable rather than failing loudly.