← Back to all free guides
A free guide by Mariah Brunner ↗ INSTAGRAM ↗ TIKTOK

Why Your
Claude Skill Isn’t Working

Your Skill is probably fine. The trigger is the problem.

You make a Skill, then hope Claude picks it up at the right moment. Sometimes it does. Sometimes it doesn’t, and you assume the Skill is broken.

Usually it’s not. In the Claude app, Claude decides when to use a Skill by reading one short field, its description, which is capped at 200 characters. If that line doesn’t match how you actually talk, Claude never opens the Skill. (How custom skills work)

Make It Run Every Time

01

Write the description like a trigger

Say what the Skill does and exactly when to use it, in the words you really type.

Before: "Helps with meetings."

After: "Preps a one-page brief before any meeting. Use when I say prep me for, meeting prep, or get me ready for a call."

02

Call it by name

You don’t have to wait for Claude to guess. Anthropic’s own tip is to be explicit, like "Use my brand guidelines skill to create a presentation." Start your message with "Use my meeting-prep skill" and it’s no longer a guess. (Using skills in Claude)

03

Use the slash command in Claude Code

In Claude Code, every Skill gets its own command. Type /meeting-prep and it runs. (Claude Code skills docs) The regular Claude chat doesn’t document a slash shortcut, so use step 02 there.

04

Make sure it’s switched on

Go to Customize, then Skills, and check the toggle. Customize is being renamed Plugins, so look for whichever one you see. Skills also need Code execution turned on under Settings, then Capabilities.

05

Check that it fired

When a Skill runs, Claude’s thinking shows that it’s using it. If you don’t see that, rewrite the description and test again with a real message.

Build One The Right Way

Paste this into a new Claude chat. Claude uses its built-in skill-creator to write the Skill, tests it, and hands you a skill file to save.

Build A Skill That Triggers
I want to turn something I do over and over into a Claude skill called meeting-prep. Use your skill-creator skill to build it properly. WHAT IT DOES: When I say "prep me for [meeting name or person]", I always want: 1. Any context about this meeting or person from my connected email and calendar (if they're connected; if not, ask me to paste what I have) 2. Who's in the meeting, what we discussed last time, and what I need to know going in 3. 2 or 3 things I should bring up 4. One page max, in bullet points, so I can scan it in 60 seconds RULES FOR THE SKILL: - Name: meeting-prep (lowercase, hyphens, matching the folder name) - Description: under 200 characters. Start with what it does, then list the exact phrases that should trigger it, like "prep me for", "meeting prep" and "get me ready for my call with". - Never invent facts about a person or past meeting. If you can't find something, say so in one line. STEPS: 1. Ask me up to 3 questions if anything above is unclear. 2. Write the SKILL.md and show me the description on its own so I can check it. 3. Test it on a made-up meeting and show me the result. 4. Package it as a skill file I can save.
Fix One That Won’t Trigger

Already have a Skill Claude keeps ignoring? This rewrites the description and gives you test messages to prove it works.

Fix My Skill Description
You are an expert at writing Claude skill descriptions, the short field Claude reads to decide when to use a skill. My skill isn't triggering when I expect it to. Fix the description. HERE'S MY SKILL: [paste the full SKILL.md, or at least the name, the description and a summary of what it does] HERE'S WHAT I TYPED WHEN IT DIDN'T RUN: [paste 2 or 3 of your real messages] STEPS: 1. In one or two lines, tell me why the current description didn't match those messages. 2. Write 3 new descriptions, each under 200 characters. Each one says what the skill does and when to use it, and names the words I actually use. 3. Pick the best one and explain why in one line. 4. Give me 5 test messages I can send to check that it triggers, plus 2 that should NOT trigger it. GUARDRAILS: - Don't change what the skill does, only the description. - No vague words like "helps with" or "various tasks". Be specific.
3 Other Things That Break Skills

01

Vague instructions

Before: "Write me an email."

After: "Write a client follow-up after a call in my voice. Keep it under 5 sentences and end with one clear next step."

02

One Skill doing five jobs

Anthropic recommends keeping each Skill focused on one workflow. Split a giant do-everything Skill into small ones with clear descriptions.

03

You never updated it

Your first version won’t be perfect. After a few uses, tell Claude "Update my meeting-prep skill to also pull action items from last time." The best Skills are the ones you’ve tweaked three or four times.