Why don't custom skills appear in Claude Code /skills list?

[mehisn]

Hello,

I created custom skills as SKILL.md files but they don't show up in /skills. The official plugin skills (caveman, frontend-design, superpowers, skill-creator) work fine. What's the correct way to add custom skills?

What I tried:
Placed SKILL.md directly in ~/.claude/skills/*/SKILL.md — didn't work
Created ~/.claude/my-skill/skill.json — wrong format, no discovery

What I've figured out:

OpenClaude only scans ~/.openclaude/plugins/marketplaces/* and ~/.openclaude/plugins/cache/* — not ~/.claude/skills/ or ~/.openclaude/plugins/custom/
Skills must live inside a plugin directory (plugins/skill-name/skills/)
But just placing files in the plugins directory isn't enough — the plugin needs to be registered (either in a marketplace manifest's plugins array, or installed via /plugin command)

Questions:

Is there a way to load skills without going through the marketplace/install system? Just having ~/.claude/skills/ or /.openclaude/plugins/local/ auto-scanned?
The "directory" marketplace source type seems like the right fit — is there a known working example?
Does /skills only show skills from installed plugins? Is there a way to register a plugin without a marketplace?

Environment: OpenClaude (v0.4.0), Linux

[subrat243]

The correct directory for custom skills in OpenClaude is ~/.claude/skills/, not ~/.claude/skills/*/SKILL.md directly at the top level.

Your analysis was almost right, but the key detail is: OpenClaude (being a fork of Claude Code) does scan ~/.claude/skills/ — you just need the right structure.

✅ Working structure:

~/.claude/skills/
└── my-custom-skill/       ← folder named after your skill
    └── SKILL.md           ← required file

Your SKILL.md must have YAML frontmatter:

---

name: my-custom-skill
description: What this skill does and when to use it.

---

My Custom Skill

Instructions for Claude go here...

The name field becomes the /slash-command. The description is how Claude decides when to load it automatically.

Why ~/.claude/skills/*/SKILL.md didn't work for you:

You likely placed the SKILL.md directly inside ~/.claude/skills/ with no subfolder, e.g. ~/.claude/skills/SKILL.md. Each skill needs its own named subdirectory.

Skill discovery precedence in OpenClaude (highest → lowest):

1. <workspace>/skills/ — project-local
2. <workspace>/.agents/skills/
3. ~/.agents/skills/ — global personal
4. ~/.claude/skills/ ← your custom skills go here
5. Bundled skills (caveman, frontend-design, etc.)

To verify it's loading, restart OpenClaude after creating the directory, then type / — your skill name should appear in the list.

Bonus — project-local skills (no global install needed):

your-project/
└── .claude/
    └── skills/
        └── my-skill/
            └── SKILL.md

This loads only when you're working in that project directory.

Hope that unblocks you! 🎉

[mehisn]

Hello!

The * was reflecting the skill name itself but unfortunately for my case I was still unable to launch my custom skills on Global level, haven't tried out yet the project level skills. :)

Will continue trying to create them.

Thank you for the current response although I can't still mark it as Answered yet.

[Blzvini]

Hi, @mehisn

I was having the same issue, but I realized I should use the .openclaude/skills folder instead of the .claude/skills folder.

Try searching for .openclaude and opening it; the skills folder probably won’t be there, so create it and place the folder containing the information and the SKILL.md file inside it.

~/.openclaude/skills/
└── my-custom-skill/ ← folder named after your skill
└── SKILL.md ← required file
🫡

[NguyenThanhDuy42124]

Hi @Blzvini,

I was struggling with the same issue for hours, and your post honestly saved me. I tried almost every solution I could find, but nothing worked until I followed your fix.

Really appreciate you sharing it. You probably saved a lot of people from a massive headache 🚀