# Claude Code Ignored My Skill 5 Times. 1 Line Fixed It

Video: https://www.youtube.com/watch?v=usYyISALQxI
Article: https://aidive.dev/videos/claude-code-skill-that-triggers/
Published: 2026-10-23

## Chapters

- [0:00](https://www.youtube.com/watch?v=usYyISALQxI&t=0s) Intro: skipped five times in five, one line fixed it
- [0:45](https://www.youtube.com/watch?v=usYyISALQxI&t=45s) Step one: what a skill is, and the prompt worth turning into one
- [2:03](https://www.youtube.com/watch?v=usYyISALQxI&t=123s) Step two: write the SKILL.md and run it by name
- [3:44](https://www.youtube.com/watch?v=usYyISALQxI&t=224s) Step three: a fresh session, plain words, skipped five times in five
- [4:49](https://www.youtube.com/watch?v=usYyISALQxI&t=289s) Step four: read why before you edit: Claude only sees the description
- [6:23](https://www.youtube.com/watch?v=usYyISALQxI&t=383s) Step five: rewrite the one line, then prove it: five in five, off and on
- [7:51](https://www.youtube.com/watch?v=usYyISALQxI&t=471s) Step six: a trigger test before your team finds out, and must-fire skills
- [9:21](https://www.youtube.com/watch?v=usYyISALQxI&t=561s) Verdict: when a skill pays, when it doesn't, and the one rule

## TL;DR

- A Claude Code skill that runs by name can still be skipped when you ask in plain words: ours loaded 0 times in 5 fresh sessions.
- Claude decides from one line per skill, the name and description, matched against your words; rewriting that description made it load 5 times in 5.
- Before editing, check /skills, start with --debug, and run claude plugin validate on .claude/skills.
- Write the description as what it does, when to use it, and the words you actually type, in the third person.
- Test with twenty requests in fresh sessions (half should load, half near misses); force must-fire skills by name or with a hook.

## Intro: skipped five times in five, one line fixed it

A Claude Code skill can run perfectly when you call it by name and still never load on its own. Ours ran every time we typed its name, and was skipped every time we asked for the same task in plain words. We watched it get skipped, read why, and rewrote the one line that fixed it.

A skill is a saved set of instructions that Claude Code picks up by itself when your request matches it. What decides the match is one line Claude reads before it chooses, and it is not your instructions. The six steps below take you from the prompt you keep retyping to a skill that loads on its own, plus a twenty-request test that catches a skipped skill before your team does.

| Test (same request, fresh sessions) | Skill loaded |
| --- | --- |
| Called by name (`/release-notes`) | 2 of 2 |
| Plain words, original description | 0 of 5 |
| Plain words, rewritten description | 5 of 5 |

## Step one: what a skill is, and the prompt worth turning into one

A skill is a folder with one file inside, `SKILL.md`. The file starts with a short header (a name and a one-sentence description) followed by the instructions. It works like a function: the caller reads the signature and the docstring, and the body only runs when it is called. Save it in your home folder to have it in every project, or inside the repository so everyone who works there gets it.

Start from the task, not the file. Pick the prompt you keep retyping and write down the exact output you want. Ours was weekly release notes: the commits since Monday, grouped by area, chores dropped, one line per change with its pull request number. On the open-source Hono repository, that long prompt produced clean notes for eight bug fixes that week, and that output became the target the skill had to hit.

Not every prompt deserves a skill. A one-off question does not, and a skill you never reuse is one more line Claude has to read. Keep a short list of the prompts you type every week; the one at the top becomes your first skill.

## Step two: write the SKILL.md and run it by name

Create `.claude/skills/release-notes/SKILL.md` in your project: a `skills` folder inside the hidden `.claude` folder, a folder named after the skill, and the skill file inside it. The folder matters. A loose `release-notes.md` does not load at all, and the docs list that as the first thing to check.

The header is a few labeled lines between two rows of dashes, and it must start on the first line of the file or Claude Code ignores it. Ours had a name, `release-notes`, and the description most people would write:

```
---
name: release-notes
description: Generates changelog documents from repository history.
---
```

Under the header go the instructions as numbered steps, the ones you would give a new teammate. Ours has five: find the commits since Monday, drop `chore` and `docs` commits, group by conventional-commit scope, write one plain line per change, and output a titled block with a short summary on top. Anthropic recommends keeping this part short. You do not need to restart: Claude Code picks up a new or edited skill in the session you are already in.

Test it by name: type a slash, pick the skill in the menu, press enter. In fresh sessions ours read the commit log, grouped the fixes by area and wrote the notes exactly as wanted, every time. The catch is that you, and everyone on your team, have to remember its name.

## Step three: a fresh session, plain words, skipped five times in five

A teammate will not type the skill's name. They will open a new session and ask the way they would ask you. So test that: open a fresh session (a new conversation with nothing loaded) and ask for the task in your own words. It has to be fresh, because a skill already used stays in the conversation and a test in that session proves nothing.

We typed "what did we ship this week?". Claude ran the commit log itself and wrote a summary its own way, with no sign of the skill. The answers were not bad, but they drifted between runs: one counted from Monday, another from the last release tag and pulled in a docs change the skill would have dropped. Across five fresh sessions the skill was skipped in all five.

Five runs is a demo, not a statistic. But a skill that works by name and is skipped every time in plain words is not doing its job, and since it passed the by-name test in step two, you would never think to look.

## Step four: read why before you edit: Claude only sees the description

Before changing a word, run three checks:

1. **`/skills`** lists every skill the session can see. Search for yours. Ours was listed and on, but the setup held 277 skills, and several plugin skills matched "release" before ours.
2. **`claude --debug`** writes a detailed log of what Claude Code loads. Look for the skills lines. Ours showed the project skill loaded, and also a warning that the skill listing was over budget, so some descriptions get cut.
3. **`claude plugin validate .claude/skills`** checks that the header is well formed. This one matters: a broken header still lets the skill run by name, but Claude can no longer match it on its own. Ours passed.

| Check | What it tells you | Our result |
| --- | --- | --- |
| `/skills` | Is the skill visible and on? | Listed, on (277 skills) |
| `--debug` | Did it load? Is the listing cut? | Loaded; listing over budget warning |
| `plugin validate` | Does the header parse? | Passed |

With the file loaded and the header valid, the cause is the description. Until it decides to load a skill, Claude does not read your instructions. It reads one line per skill, the name and the description, and matches them against your words. Ours said "generates changelog documents from repository history"; the request said "what did we ship this week". The two sentences share no word. Claude never read our instructions; it read one line, and that line did not use our words.

The budget warning means Claude Code trims descriptions to fit, least-used skills first, and a brand-new skill is the least used of all. Check that yours survived: ours did, since requests using its own words still loaded it.

## Step five: rewrite the one line, then prove it: five in five, off and on

Write the description for the moment someone asks, not for the file. Say what the skill does, when to use it, and the words people actually type. Ours became:

```
description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.
```

Anthropic's authoring guide adds one rule: write it in the third person ("Writes"), never "I can help" or "You can use this".

Then prove it in a fresh session with the same request. "What did we ship this week?" now loaded the skill before Claude touched anything, and the notes came out in our format, in five of five fresh sessions.

Run a baseline too: switch the skill off with a skill override in your local settings file (it hides the skill without deleting it). With it off, Claude went back to its own summary; with it on, the skill loaded. The skill made the difference, not luck.

The limit: a description that matches too much makes the skill fire where it should not. Add the words you really use, not every word you can think of.

## Step six: a trigger test before your team finds out, and must-fire skills

One request proved the fix; a skill a team relies on gets asked for in many ways. Anthropic's skill-creator describes the test: twenty requests, a mix that should load the skill and near misses that should not. A near miss sounds close but is a different job, such as "write a commit message for my staged changes". Run each request in its own fresh session and note whether the skill loaded. The skill-creator's own script did not see the skill on our Claude Code version, so we ran the same twenty requests with a short script of our own.

| Description | Should-load requests that loaded it | Near misses that loaded it |
| --- | --- | --- |
| Original | 4 of 10 | 0 of 10 |
| Rewritten | 10 of 10 | 0 of 10 |

Before the rewrite the skill loaded only on requests that already contained "release notes", "changelog" or "release": the word matching from step four, in plain sight. After the rewrite it loaded on every request that should load it and still stayed out of every near miss.

For a skill that must never miss, force it. Type its name, or add a hook (a small script Claude Code runs at a fixed moment, here on every message you send) whose output tells Claude to use the skill for that task. With the hook in place, even the original description loaded on the plain request. The limit: every test run costs real usage and a hook adds a line to every message, so keep it for the few skills that truly must fire. Rerun your list whenever you change the description.

## Verdict: when a skill pays, when it doesn't, and the one rule

Our release-notes skill worked every time by name, was skipped in every fresh session in plain words, and one rewritten line made it load every time. The reason: Claude reads one line per skill before it decides, and it matches your words, not your intentions.

A skill pays for a task you repeat with a fixed output: weekly notes, a pull request description, a release checklist. It does not pay for a one-off question, and it is not the tool for a rule that must always hold; that is a hook's job. A pile of unused skills costs you too, because with too many of them Claude Code starts cutting descriptions, least used first. A good description raises the odds but will not make a skill fire for a job it was never meant for, and a handful of runs is a demo, so your list of test requests is the real check.

The one rule: write the description in the words you actually type when you ask for the task.

## FAQ

### Why doesn't my Claude Code skill load automatically?

Until it decides to load a skill, Claude reads only each skill's name and description and matches them against your request. If the description doesn't use the words people type, the skill is skipped even though it runs fine by name.

### How do I write a Claude Code skill description that triggers?

Say what the skill does, when to use it, and list the phrases people actually type for that task, written in the third person. Ours went from 0 of 5 to 5 of 5 loads after that rewrite.

### How do I check why a Claude Code skill isn't loading?

Type /skills to confirm it is listed and on, start Claude Code with --debug to see the skills it loaded and any listing budget warning, and run claude plugin validate on .claude/skills to catch a malformed header.

### How do I test whether a Claude Code skill triggers reliably?

Write about twenty requests, half that should load the skill and half near misses that shouldn't, and run each in its own fresh session. A skill already used stays in the conversation, so same-session tests prove nothing.

### Can I force a Claude Code skill to always run?

Yes: call it by name with a slash command, or add a UserPromptSubmit hook whose output tells Claude to use the skill. Keep the hook for the few skills that must never miss, since it adds a line to every message.

## Sources

- [Claude Code docs: Skills](https://code.claude.com/docs/en/skills) — docs
- [Claude Code docs: Debug your config](https://code.claude.com/docs/en/debug-your-config) — docs
- [Anthropic: Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — docs
- [anthropics/skills: skill-creator SKILL.md and scripts](https://github.com/anthropics/skills/tree/main/skills/skill-creator) — GitHub
- [Measuring Claude Code skill activation with sandboxed evals (Scott Spence)](https://scottspence.com/posts/measuring-claude-code-skill-activation-with-sandboxed-evals) — blog
- [Claude Code skills activate 20% of the time, how I got to 84% (r/ClaudeCode)](https://www.reddit.com/r/ClaudeCode/comments/1oywsa1/) — Reddit
- [Issue #9716: Claude Code not aware of skills in .claude/skills](https://github.com/anthropics/claude-code/issues/9716) — GitHub
- [My Claude Code skills in production: what the audit taught me (dev.to)](https://dev.to/ohugonnot/my-claude-code-skills-in-production-what-the-audit-taught-me-2eeg) — dev.to


## Free resources

- [The skill-that-fires kit: make a Claude Code skill load on its own](https://aidive.dev/club/free-resources/claude-code-skill-that-triggers-pack/)