Why is it that it's installed but cannot be detected?

[bbhxwl]

Why is it that it's installed but cannot be detected?

[naimkatiman]

This is a common issue — here are the most likely causes and fixes:

1. Missing or malformed SKILL.md frontmatter

Every skill must have YAML frontmatter at the top with at least name and description:

---
name: my-skill
description: "What this skill does — Claude uses this to decide when to trigger it"
---

If the frontmatter is missing or has a syntax error (wrong indentation, missing quotes on special characters), Claude Code won't detect the skill.

2. Wrong directory structure

Claude Code looks for skills in specific paths:

# Project-level (per repo)
.claude/skills/<skill-name>/SKILL.md

# Global (all projects)
~/.claude/skills/<skill-name>/SKILL.md

A common mistake is placing the SKILL.md directly in .claude/skills/SKILL.md instead of inside a named subdirectory. The correct structure:

.claude/
└── skills/
    └── my-skill/          ← needs this folder
        └── SKILL.md

3. Skill installed globally but expected locally (or vice versa)

If you installed globally (~/.claude/skills/) but you're working in a project that expects project-level skills (.claude/skills/), it might not resolve.

Quick debug command:

# Check if Claude sees your skills
ls -la ~/.claude/skills/
ls -la .claude/skills/

# Verify SKILL.md has valid frontmatter
head -5 ~/.claude/skills/*/SKILL.md

4. Cache issue

Sometimes Claude Code caches the skill list. Try:

• Restart Claude Code (/quit then relaunch)
• Or start a new conversation

I maintain a skill called continuous-improve that installs across Claude Code, Codex, and Cursor — I ran into this same detection issue during development. The fix was always one of the above.

Hope this helps — let me know if you're still stuck and I can help debug further!

---

See it in action: before vs after

Before (agent without discipline):

After (agent with continuous-improve installed):

Install: npx continuous-improve-skill — works with Claude Code, Codex, Cursor, and ChatGPT.
Repo: naimkatiman/continuous-improve-skill

[mj-deving]

@naimkatiman covered the basics well — the directory structure and frontmatter points are correct. Let me add what I've hit myself and a few things the troubleshooting above misses.

The actual checklist (in order of likelihood)

1. The subdirectory thing — this trips up almost everyone

Claude Code doesn't scan for loose SKILL.md files. It needs the named-folder structure:

~/.claude/skills/my-skill/SKILL.md     ← this works
~/.claude/skills/SKILL.md              ← this does NOT

The folder name becomes your skill name if you don't set one in frontmatter. Quick check:

find ~/.claude/skills -name "SKILL.md" -type f

If any result doesn't have a directory between skills/ and SKILL.md, that's your problem. Move it:

mkdir -p ~/.claude/skills/my-skill
mv ~/.claude/skills/SKILL.md ~/.claude/skills/my-skill/SKILL.md

2. Frontmatter — you need at least a description

Without a description field, Claude has nothing to match against. It won't know when to trigger your skill. Bare minimum:

---
name: my-skill
description: "Does X when you ask for Y"
---

Common gotchas: missing the closing ---, tabs instead of spaces in YAML, or a BOM character your editor silently added before the first line. If you're not sure, head -1 SKILL.md | xxd | head -1 will show you if there's invisible junk before the ---.

3. You created the skills/ directory after starting Claude Code

This one's subtle. If ~/.claude/skills/ didn't exist when you launched your session, Claude Code won't watch it. Adding skills inside an already existing directory gets picked up live. But creating the top-level directory itself? Requires a restart.

Just /quit and relaunch. Or /clear for a new conversation.

4. Scope mismatch

Project skills live in .claude/skills/ (relative to repo root), global skills in ~/.claude/skills/. If you installed a skill at project level but switched to a different repo, it won't be there. Obvious in hindsight, easy to miss in practice.

5. Too many skills — budget exhaustion

This one's less common but real. Claude Code caps skill descriptions at roughly 8,000 characters total. If you have 30+ skills, descriptions get truncated and Claude loses the keywords it needs to auto-trigger. Your skill still works with /skill-name directly — it just never fires on its own.

Fix: export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000 or front-load your description with the trigger words that matter.

---

@bbhxwl if you can share your directory structure (find ~/.claude/skills -type f) and the first few lines of your SKILL.md, I can tell you exactly which one it is.