How to Make Claude Code Use Your Skills Automatically

Hello builders,

The skill you installed should do its job the second you ask for the job, in plain words, in a brand new session, and for a folder of 20 or 40 skills you should know which ones actually run. When one never runs, you are still paying for its line in the listing of every session. If you searched “claude skill not triggering”, the fix is usually one line of frontmatter, the description, plus a test that proves the fix held.

@K_chachamaru posted in Japanese on X about spelling out the full path to their skill and being told it didn’t exist. When they pushed back, Claude confessed:

“Found it. I can read it. The resolver works too. But I didn’t register it as a Skill. I read the text and imitated it by hand.”

You get output and no sign that the skill never ran.

What Claude actually reads

When you type a request, Claude decides from a listing of names and descriptions, and the body you wrote so carefully has not loaded yet. Anthropic’s own page says the listing has a budget, and that the quiet skills lose their descriptions first:

The listing always contains every skill name, but if you have many skills, Claude Code drops some descriptions to fit the listing’s character budget, which removes the keywords Claude needs to match your request. The budget scales at 1% of the model’s context window. When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least, so the skills you use most keep their full text.

(Claude Code docs, “Extend Claude with skills”)

So the description carries most of the match, together with the name. Here is the same skill written three ways, from the book:

Version 1 reads “A powerful workflow for professional client communications.” and version 2 reads “Writes client status updates from raw notes.” Version 3 adds the inputs and the ways a person actually asks:

---
name: writing-client-updates
description: >
  Writes a client-facing status update from raw notes, meeting minutes, or a
  list of tickets. Use when the user asks for a client update, a status report,
  a weekly summary for a customer, or wants rough internal notes turned into
  something a client can read. Covers progress, blockers, and next steps.
---

Write it in third person, because the description is injected into the system prompt and Anthropic’s best practices page warns that a mixed point of view causes discovery problems. Name the inputs and the conditions with the words you’d type. And make it a bit pushy: Anthropic’s own skill-creator says Claude has a tendency to “undertrigger” skills and asks authors to make descriptions “a little bit ‘pushy’”.

I ran it 18 times

I ran the versions in fresh claude -p sessions on Claude Sonnet 5.5 with Claude Code 2.1.304, with my 63 personal skills also in the listing. The phrasings were “turn these notes into something I can send the client”, “write up this week for Acme” and “these minutes need turning into something for the customer”.

With the skill named writing-client-updates, all three versions fired 3 of 3, the vague one included, because the name already said “client”. That differs from the book’s picture, and the name is why. Then I renamed the folder to cu-helper, a name like plenty of skills on GitHub have, and tested versions 1 and 3 under it. Version 1 fired 2 of 3 and missed “write up this week for Acme”, while version 3 fired 3 of 3. How many skills in your folder have a name like that? I also sent version 3 three requests that should leave it alone (a standup note, a personal summary and a meeting write-up) and it stayed quiet on all three.

On my machine a job-shaped name did most of the matching, and the description picked up the requests that never said “client”.

Prove it in 3 fresh sessions

Here is the test we run, and it takes about ten minutes.

1. We write down five ways a person would ask for the job, including one lazy one and two messy multi-part ones. The skill-creator file says simple one-step requests “may not trigger a skill even if the description matches perfectly”, so we test on the real, messy version.
2. We rewrite the description in the skill’s file, ~/.claude/skills/<skill-name>/SKILL.md for a personal skill, so all five phrasings share real words with it.
3. We check it parses. The skills docs say malformed frontmatter loads the body with empty metadata, so /skill-name still works and Claude can’t match your description. claude --debug shows the parse error, and the opening --- has to be the very first line of the file.
4. While testing, we add one line to the body, Start the reply with SKILL:writing-client-updates, and delete it afterwards. To be sure, run the phrasing with claude -p "<phrasing>" --output-format stream-json --verbose and look for a tool call named Skill, which is the signal I trust most.
5. We start claude in a new terminal three times, type a different one of the five phrasings in each, and never type the name of the skill. We log every run, failures included.

We use a fresh session each time because the window where we just edited the file already has the instructions in it, and we would be measuring our own conversation. Here’s the book’s log, trimmed, from the six runs in the picture (a separate test from my 18 runs):

## writing-client-updates — trigger log

| Run | Phrasing used | Fired? | Notes |
|---|---|---|---|
| 1 | "turn these notes into something I can send the client" | NO | v2 |
| 2 | "write up this week for Acme" | NO | v2 |
| 3 | "status report for the client, here's the ticket list" | YES | v2 |
| 4 | "turn these notes into something I can send the client" | YES | v3 |
| 5 | "write up this week for Acme" | YES | v3 |
| 6 | "these minutes need turning into something for the customer" | YES | v3 |

Three consecutive clean fires: runs 4, 5, 6. Name never typed.

Keep the failed rows, because after a model update they are the only record of the phrasings we already fixed.

I want three in a row before I trust a skill, which is also how many times the skill-creator tuning loop runs each query, because Claude does not answer the same way every time.

If it still will not go, ask What skills are available? and call it with /skill-name. When the name works and the plain request never does, go back to step 2 and fix the description.

Pick the skill you’ve never seen run on its own and give it ten minutes today.

Now go build something this weekend!

John Cook