You've installed a Claude Skill and it's not working. How to fix it.

I spend a decent amount of time looking at other people's published Claude / Claude Code skills.

What a skill actually is

A Claude (or any model) skill is an articulation of repeated behavior that I want my model to know and do for me, with enough detail that I can simply say, "create an expert profile for person_name" and it knows what I want it to do.

I've written about using Claude skills before.

But since I know tons of people are out there doing similar, I regularly look for other people's published skills.

Installing one is easier than you'd think

Often these skills are on GitHub, which - if you're not technical - can be scary.

But installing a skill doesn't have to be difficult. I can simply tell Claude, here is a url for a skill. Can you review it and install it for me. Boom it's done.

Here's the thing - installing a skill isn't hard. Even making a skill isn't too hard. Claude has a skill (yes, very meta) on building skills. So I can also say, "that work we just did to build out an expert profile, can you turn that into a skill?"

So where's the hard part?

So if finding skills, installing skills, and learning and building skills, where is the hard part? Why am I even writing about this today?

Because you can install a skill and never have it run!

Frustrating, right? It is. And as I've pulled in some skills, I've had this happen.

The tricky part is you may not even realize it. There's no error message. Claude just answers like normal. But the result feels generic, or it doesn't follow the format you expected, or Claude never mentions the skill by name. That's your tell that the skill sat there unused.

Why a skill won't run: progressive disclosure

Is it because the skill is bad. Not exactly. To understand it, you have to understand how skills work. It's the notion of progressive disclosure.

The skill file has more than instructions. It can have output formats, resource files, examples and more. You don't want all that info, for every skill you have, pre-loaded into every chat.

The description is the trigger

So what Claude does is look at your prompt and decide whether a skill is needed. It makes that call by reading the skill's description. The front matter is just the little labeled block at the very top of the skill file, and the description is one line inside it - a short bit of text that tells Claude what the skill is for and when to use it. That description is the trigger. It's the one thing Claude checks before deciding to load the rest.

So imagine my expert profile skill has a thin description, something like "creates an expert profile."

Now imagine I tell Claude, "build me a detailed dossier on person_name" - it may never see my skill, because nothing in that thin description reaches toward the word dossier.

That's not likely to happen when it's a skill you created. Because you're likely to use the terms that you used when you built it. But when you are using someone else's skill, it turns out it can be common.

The quick fix: name the skill

The fastest fix needs no editing at all. Just name the skill in your prompt. Instead of "build me a dossier on person_name," say "use the expert profile skill to build a dossier on person_name." That forces it to fire, every time.

The durable fix: widen the description

The quick fix works, but it means remembering the skill's name every time. The better long-term move is to review the front matter and even "talk" about it with Claude. A simple conversation can tweak the description so the skill is easier to call.

You can paste something as plain as this: "Can you widen this skill's description so it also triggers on dossier, deep background, or research?" That one change makes it much easier to call and use new Claude skills from others.