Okay so — you have typed some version of the same paragraph into Claude Code every day this week. Maybe it is "check this migration for missing indexes." Maybe it is "write commit messages like the last ten." You paste it, it works, you close the tab, and tomorrow you type it again, because there was never anywhere to put it.
There is somewhere to put it. It is a text file called SKILL.md, it has two required lines, and by the end of this you will have written one, watched it get picked up on its own, and used it on something real in your own project. Ten minutes, folder to firing.
The swamp you already found
If you searched anything like "claude code skill not triggering" to get here, you already met the problem this piece exists to fix. There is a whole cluster of posts making the identical point — description matters more than name — and several dress it up with a number nobody ran: "650 trials," "100% vs 37% activation," no methodology, no repo to check.
I'm not going to sell you that same one true sentence as a discovery, because it isn't one — it's the most repeated claim in this corner of the internet, and it also happens to be correct. What none of those posts did was build the thing and show you the moment it works, and the moment it doesn't. So that's what this is.
What Claude Code actually requires
Here's the whole spec, because it's short enough to just state: a skill is a folder containing one file, SKILL.md, with YAML frontmatter (plain-text settings at the top) holding exactly two required keys — name and description — followed by a plain paragraph of instructions. Not a license field, not a version number, not a tools list. I built one and ran it through a YAML parser before claiming that to you:
import yaml, re content = open('SKILL.md').read() front, body = re.match(r'^---\n(.*?)\n---\n(.*)$', content, re.S).groups() data = yaml.safe_load(front) print(list(data.keys()))
['name', 'description']
Two keys. name is lowercase-with-hyphens, capped at 64 characters. description is capped at 1024. Everything below the second '---' is the instruction paragraph the agent reads once it decides to use the skill — and that decision is the whole game, because here's the part the SEO cluster undersells without proving: at the start of every session, Claude Code reads only the name and description of every skill in your project. Not the body. The body loads later, and only if the description convinced it this task is a match.
Step 1 — pick the paragraph you keep retyping
Use your own repeated instruction, not mine — this replaces something you're already doing by hand. If you don't have one yet, "write a commit message in the style of my last few commits" is a good first skill: everyone who uses git has typed some version of it.
Step 2 — write the description, and prove to yourself it's load-bearing
The description is not a summary of what the skill does. It's the trigger condition for when the skill should fire, and I didn't want to just tell you that, so I isolated it.
I wrote one SKILL.md body and gave it a deliberately useless name — 'helper' — in every version, so the name field couldn't be quietly doing the work. Then I staged a change — added it to git's index, ready to commit — in a repo with three prior commits and asked for a commit message, twice per version, watching the tool calls.
Version one, description as a label instead of a trigger:
name: helper description: My rules.
Skill tool calls across two runs: zero. Claude still wrote a passable commit message — it's a capable model and this isn't a hard task — but it did it from general knowledge, not from the specific rules sitting in the body. The skill was in the folder the entire time and never got read.
Version two, same body, same useless name, only the description changed:
name: helper description: Use when the user asks for a git commit message, wants to commit staged changes, or asks for a message "like the last few commits". Match this project's existing commit style instead of writing a generic one.
Skill tool calls across two runs: two for two, and it was the first tool call each time, before git was ever touched.
That's the isolated result: with the name field held constant and uninformative in both directions, changing only the description flipped the skill from never firing to firing every time in those two runs. Write the description as a label and the skill sits in the folder forever, structurally invisible. You'll conclude — reasonably, but wrongly — that skills don't work.
Step 3 — the instruction paragraph
Below the closing '---', write what the agent should actually do. One real paragraph, not a checklist wearing a skill's clothes:
Before writing a commit message, run 'git log --oneline -10' to see the last ten commit messages in this repo. Match their format: same tense (imperative vs past), same length (short one-liners vs longer bodies), same prefix style ('fix:', 'feat:', or none at all). Then run 'git diff --staged' to see what actually changed, and write one new commit message in that same style describing the specific change. Never fall back to a generic message like "Update files."
Notice this names actual commands, not vibes. "Match the style" isn't something an agent can execute; "run git log --oneline -10 and match the tense and prefix pattern you find" is.
Step 4 — save it and check what actually has a limit
Make a folder called .claude/skills/commit-style inside your project, and save the frontmatter plus the paragraph above as SKILL.md inside it — with a real name this time, since you're keeping this one:
--- name: commit-style description: Use when the user asks for a git commit message, wants to commit staged changes, or asks for a message "like the last few commits". Match this project's existing commit style instead of writing a generic one. --- Before writing a commit message, run 'git log --oneline -10' to see the last ten commit messages in this repo. Match their format: same tense (imperative vs past), same length (short one-liners vs longer bodies), same prefix style ('fix:', 'feat:', or none at all). Then run 'git diff --staged' to see what actually changed, and write one new commit message in that same style describing the specific change. Never fall back to a generic message like "Update files."
I counted this one before writing a word of this piece: 16 lines. The body itself has no hard line limit — Anthropic's guidance is just to keep the whole file short, roughly under 500 lines — but the frontmatter fields do: name capped at 64 characters, description at 1024. Mine come in at 12 and 208, checkable on your machine in sixty seconds, on a real limit instead of one I made up. This isn't a framework you install and trust. It's short enough to read in full, every time.
Step 5 — watch it fire
Restart Claude Code in that project, or open a fresh session — skills load at session start, so a skill you just wrote a folder for doesn't exist yet to a session that's already running. Then do the thing you'd normally do by hand: stage a change and ask for a commit message.
Watch the transcript the same way I did above. If your description names the moment ("asks for a git commit message"), the Skill tool call appears first, before anything touches git — that's the body loading because your actual request matched the sentence you wrote. If you skipped Step 2 and left the description as a label, this is where it goes quiet: the folder's right there, but the skill never gets pulled in, because nothing you typed looked like a match to an agent that only ever read the label. If it still won't fire, point the Step 2 parser at your own SKILL.md — same silent failure, different cause.
Why this matters
The failure mode doesn't look like an error. It looks like nothing — you ask, the agent answers fine in its own default style, and you retype your instruction like you did yesterday, never finding out the skill was sitting three folders up the whole time, unread. A skill with a weak description just quietly loses to your habit of typing the paragraph yourself, and you walk away thinking the feature doesn't work rather than thinking you wrote one sentence badly.
Get the description right and something changes that isn't really about git commits. You stop being the person who retypes the same paragraph into every session and become the person who packaged that workflow once, in a shape the agent can find on its own. It's also the first time your instructions outlive the session you typed them in.
Final thought
Don't build the commit-style skill if you already have your own repeated paragraph — build that one instead, today, using the two things that actually matter: a description that names the moment you'd reach for it, and a body with real commands in it, not vibes. Then open a fresh session, try the exact request you'd normally type by hand, and read the transcript for the Skill tool call before anything else happens. If it's missing, check two things in order. First, did you restart the session — skills only load at the start of one. Second, reread your description, and ask whether it says what the skill does or when to reach for it.