When Skills Go Wrong

Nothing happened

You wrote the skill. You asked for the thing. Out came a perfectly reasonable answer in Claude's ordinary style, with none of your rules applied, and no explanation of why.

This is the single most common experience of a first skill, and it is almost never the instructions. Four things go wrong, they look different, and each has a different fix.

One: it never fired

By far the most likely failure. The skill was not ignored, it was never opened, because the description did not match the words you typed.

Remember the shelf of ring binders. Claude reads the spines against the task in front of it. If your spine says style and structure guidance for internal documentation, and you typed "can you tidy these up for me", nothing on that shelf looks relevant.

The fix is to stop describing the topic and start describing the moment, in the words you genuinely use. Go and look at what you actually typed the last three times. Those phrasings are the ones your description has to catch.

Two: it fired when you did not want it

The opposite complaint, same root cause. A description broad enough to catch everything will catch everything. You ask for a quick note to a colleague and receive it structured into decisions, actions and open questions, because the description said something like use when writing anything work-related.

Narrow the description until it names one situation. If the skill genuinely serves two different situations, that is usually two skills.

Three: two skills disagree

You have a skill saying always open with a one-line summary and another saying never open with a summary. Both descriptions match the task. Both sets of instructions load. What comes back is a compromise nobody wrote, and it will be inconsistent from one day to the next.

This is not something to fix by adding a third skill to arbitrate. Overlapping scope is the problem, so either merge the two into one skill that states which rule wins where, or narrow both descriptions until they stop meeting.

Four: too long to follow

Lesson 1 said a skill can be long because it costs nothing until used. That is true about cost. It is not a promise that everything long gets followed.

Instructions fail when they sprawl: forty rules of equal weight, conditions inside conditions, three paragraphs of context before the first instruction, or the same rule stated four times in slightly different words. The rules that matter get lost among the ones that do not.

The fix is editing. Cut to the rules whose absence you would actually notice. If a rule has never once been broken in the work you have seen, it is not earning its line.

Telling them apart

From the outside all four look the same: an answer that is not what you wanted. Separating them takes one attempt and one question.

Ask for the job in your natural wording, then ask which skills were considered. If none were, that is the first failure and the description is the thing to fix. If yours came up on a task you never meant it for, that is the second. If it came up and the output contradicts itself between one run and the next, go looking for a second skill whose description also matches. And if it came up but only some of your rules landed, the instructions have sprawled and need cutting.

Before you answer my next request, tell me:

Which skills, if any, do you consider relevant to it?
For each one, which part of its description made it relevant?
If none apply, say so plainly and say what you would have
needed to see in a description for one to apply.
Then answer normally. My request: [the thing you actually want]

This is a skill description that is not being triggered:
[paste the description]
These are three things I actually typed when I wanted this skill
to apply, word for word:
[paste them]
Rewrite the description so it names the situations in those three
examples, using their kind of wording. One or two lines. Do not
summarise the instructions, and do not make it broader than those
three situations.

Here are the instructions from a skill of mine. They are too long
and I think that is why they are not being followed properly.
Sort every rule into three groups:

Load bearing: the output would be visibly wrong without it
Nice to have: it improves things but nothing breaks
Redundant: it repeats another rule, or is already implied
Then show me a version containing only the load bearing rules.
THE INSTRUCTIONS:
[paste them]