A skill description can't make a model want the skill

Your agent skill doesn't load for a prompt that should clearly trigger it. A fix that comes to mind is to put the prompt's words into the description. I tried that, and it changed nothing.

The probe that failed

I was rewriting a skill that teaches an agent how to write skills. To test its description, I ran trigger probes: test prompts that should, or should not, make the agent load the skill. Each probe was one non-interactive run of Claude Code on a small current Claude model of the Haiku class.

The second probe is a near miss: it sounds like writing, but it isn't about skills. Nothing loaded, which is correct.

The first probe is the real phrasing a user might type. The new description quoted "make that a skill" word for word, and the skill still didn't load. I checked the transcript: both descriptions were in the session's skill list, so the model had seen them.

A description is the short text at the top of a skill file. It tells the model what the skill is for and when to use it. Here is the one the writing-skills skill has today in my skills repository (opens in a new tab):

description: >
  Agent skill authoring guide. Use when users ask to "make that a skill" or "turn this into a skill",
  keep explaining the same steps to an agent, ask whether a workflow should become a skill,
  create, edit, or review a SKILL.md, or fix a skill description so agents discover it.

It names the topic first, then lists the situations that should trigger it, in the words a user would type. The probe "make that a skill" appears in it almost word for word, so you'd expect a load. That's the trap: the match looks like proof, but it only shows the model could have chosen the skill.

What the model did instead

The transcript showed why. The model made no attempt to load a skill. It read files and ran shell commands to look for release docs, and then asked which repository I meant. It treated the job as "find the release steps", and that job needs no skill about writing skills.

Shortened, the run looked like this:

1. Search the files for release docs.
2. Run a few shell commands to look around.
3. Ask which repository I meant.

No step in that list asks for a skill. If you only look at the final answer, you see "skill not loaded". If you read the steps, you see a model that was busy with a different job.

Think of a label on a toolbox. A better label helps someone who is looking for a tool. It doesn't help someone who has decided to do the job by hand. The label is the description, and doing it by hand is the model starting the task itself. Unlike a person, the model reads every label each time, so the label was seen. It just wasn't needed.

So the miss was a load decision, not a wording problem. Quoting the probe phrase only fits the description to that one test. To check a fix, use phrasings that the description was not written from.

Say your probe is "make that a skill". Here are other ways a user could ask for the same thing:

• "Can you turn these steps into something you can reuse?"
• "Save this workflow so I don't have to explain it again."
• "Next time, just do this the way we did it today."

If the skill loads for none of them, rewording the description won't be the whole answer. If it loads for some, you've learned which kind of request the model connects to the skill.

Test the right copy

One trap in the setup: if a skill with the same name is already installed globally, a probe may load that copy instead of yours. I gave the new version a distinct name for the probes, so a load would show which copy the model picked. If your installed skill is called writing-skills, name the test copy something like writing-skills-test.

This is one run per probe, on one model, so treat it as one observation, not a measurement.

Next time a probe fails, read what the model did before you touch the description.