*Most skills don't work. The ones that do follow the same 6 patterns. *
I'll walk through each one with real examples from skills people actually use daily.
By the end you'll know exactly why your custom skills don't fire and how to fix them👇
Before we dive in, I share daily notes on AI & vibe coding in my Telegram channel: https://t.me/zodchixquant🧠
The 30-second refresher
A skill is a markdown file with YAML frontmatter at the top and instructions below.
You put it in ~/.claude/skills/skill-name/SKILL.md. C
laude loads it automatically when context matches the description, or you invoke it manually with /skill-name.
That's the whole architecture. The hard part is what goes inside SKILL.md.
Pattern 1: Description tells Claude WHEN, not just WHAT
This is the single most important field. Claude scans descriptions of all available skills before deciding which to load. If your description only says what the skill does, Claude won't know when to use it.
Bad description:
Good description:
The good one tells Claude: what the skill does + when to trigger it + which keywords to listen for.
Skills with descriptions under 50 characters get invoked 3-5x less often than skills with proper trigger context. Front-load the use case in the first 250 characters because that's all that gets included in Claude's context budget.
Pattern 2: Be directive, not conversational
Skills are instructions, not chat. Use imperative verbs.
Conversational (weak):
Directive (strong):
Claude follows imperative instructions much more reliably than questions or polite requests.
Look at any skill from the official Anthropic repository, and you'll see the same pattern: direct verbs, numbered steps, explicit output formats.
Pattern 3: Specify the output format
This is where most custom skills fail. They tell Claude what to do but not what the output should look like. Claude makes up a format every time and the results are inconsistent.
Without output format:
You get: sometimes one line, sometimes paragraphs, sometimes with prefixes, sometimes without.
With output format:
Now you get the same output structure every time. The skill is reusable.
Pattern 4: Include the "read first" step
The best skills don't assume Claude knows your project. They tell Claude to look first.
Take the /test skill from the awesome-claude-skills repo. Instead of "write tests," it does this:
The "read first" step is what separates skills that produce code matching your project from skills that produce generic code that breaks your linter.
Pattern 5: Define what the skill does NOT do
Counterintuitive but powerful. The best skills explicitly list what's out of scope.
From Anthropic's official PDF skill:
Why this matters: when a user asks for something the skill can't do, Claude doesn't try and fail.
It either picks a different skill or asks for clarification. You get fewer broken outputs and more correct routing.
This pattern shows up in 70% of high-quality skills and almost never in low-quality ones.
Pattern 6: Keep it under 500 lines
Every skill loads into Claude's context when invoked. A 2000-line skill eats 5000+ tokens before doing anything.
The longer the skill, the more chance Claude loses focus halfway through and starts ignoring instructions at the bottom.
The official Anthropic skills (frontend-design, code-review, security-guidance) are all under 300 lines. The community skills with the most installs (Superpowers, Context7, mcp-builder) are similarly tight.
If your skill is getting long, split it. Use the progressive disclosure pattern:
In SKILL.md you reference the other files:
Claude loads the supporting files only when the task actually needs them.
A real example: The /commit skill, broken down
Here's a /commit skill that follows all 6 patterns. This is what good looks like:
Notice:
- Description tells Claude WHEN
- Instructions are directive (imperative verbs, numbered steps)
- Output format is explicit (the commit message structure)
- "Read first" step is built in (git status, git diff)
- Out of scope is defined
- Total length: under 50 lines
This skill works on every project, in every language, every time.
What kills skills
The skills that don't work share these failure patterns:
If your custom skill checks 3+ of these boxes, it's probably not getting invoked or producing bad output.
How to fix existing skills
Pull up your weakest skill (the one Claude never invokes). Run through this checklist:
Fix the failed ones. Test by asking Claude something the skill should handle without invoking it manually.
If Claude picks the right skill, your description is working. If it picks a different skill or none at all, the description needs more trigger context.
The compounding effect
Bad skills make Claude slower (eating context for nothing), produce inconsistent output (no format), and route incorrectly (vague descriptions).
Good skills compound in the opposite direction.
Each well-written skill makes Claude better at picking the right one for any task. The skills become a system, not a collection.
The skills folder of someone who's been doing this for 6 months looks completely different from someone who just started.
Same Claude, completely different output quality.
I share daily notes on AI, finance, and vibe coding in my Telegram channel: https://t.me/zodchixquant
Thanks for reading🙏🏼
