Your Claude Code Skill Won't Trigger? The Description Is Doing 90% of the Work

If you've ever pasted the same six-paragraph instruction block into Claude Code for the fourth time in a week, you already know the problem. You have a workflow in your head — "scout the repo, check the changelog, draft in this tone, never invent numbers" — and every single session you re-explain it from scratch. Your clipboard is basically a co-worker at this point.

A skill fixes that. It's the mechanism that lets you teach Claude Code (or Codex, Gemini CLI, Cursor — they share the same open standard) a workflow once and have it show up on its own when it's relevant. The catch: most first skills never trigger, or trigger at the worst possible moment. And almost always, the reason is one line you probably rushed.

Let's build one properly.

What a skill actually is

Strip away the mystique and a skill is a folder with a markdown file named SKILL.md. That's it. The file has two parts:

---
name: my-skill
description: <when should this fire?>
---
 
# Everything below is just instructions the model reads
# once the skill is activated.

The frontmatter (name, description) is the router. The body is the playbook. People spend all their effort polishing the playbook and write the router in five seconds — which is exactly backwards, because the model never even reads your beautiful playbook unless the router does its job first.

When something deserves to be a skill

Not every prompt needs to graduate into a skill. My rough rule:

• You've done the same multi-step thing three or more times.
• It has rules you keep forgetting (a tone, a forbidden phrase, a "never push to main" guardrail).
• Getting it wrong is annoying to undo.

If all three are true, you're not writing a prompt anymore — you're writing a procedure. Procedures belong in skills. One-off questions don't.

The part that matters: the description is the trigger

Here's the mental model that fixes most broken skills: the model decides whether to load your skill by reading the description and almost nothing else. So the description can't describe what the skill contains. It has to describe when to use it.

Compare:

# ❌ describes the body
description: A skill that publishes blog posts with images and validation.
 
# ✅ describes the trigger
description: Publish a deep-dive post to the blog. Use when the user says
  "publish this week's post" or when the weekly cron fires.

The first one is a table of contents. The second one is a condition. Only the second reliably fires, because it gives the model a concrete "if this, then me" to match against.

Real example: one of my own publishing skills uses description: ... Use when Jay invokes "AGENT.WATCH" workflow or when the weekly cron fires. It names the exact phrases and the exact event. No guessing.

And if there are moments it should stay quiet, say so in the body — the description gets it in the door, the body sets the boundaries:

Real example: that same skill has one blunt line near the top: "Do not run unprompted from a casual conversation — this writes to main." Triggering is a two-sided problem. Getting it to fire is half; stopping it from firing when you're just chatting is the other half.

Write the body like a runbook, not an essay

Once the router works, the body is where you encode the how. Treat it like a runbook a tired stranger could follow:

1. When to run — restate the trigger conditions in plain language.
2. Hard rules — the non-negotiables. Tone, "no PR / commit to main", word limits, forbidden phrases.
3. Steps / phases — numbered, each with "do this → here's the command → here's what usually breaks."
4. Failure handling — what to do when a step fails (abort? notify? retry once?).

Keep it scoped to one job. A skill that "manages the whole blog" will be vague at exactly the moments you need it sharp. A skill that "publishes one post and stops" is easy to reason about — and so is its description.

Bake your guardrails into the skill, not your memory

This is the upgrade most people skip. A skill isn't just instructions — it's the right place to put the checks that stop a known failure from happening again. If you've watched an AI confidently do the wrong thing once, encode the fix so it can't recur.

Real example: AI assistants love to make a paragraph look authoritative by sprinkling in numbers — a Lighthouse score here, a "40% faster" there — that nobody actually measured. After that bit me, I added a verify_numbers.py check to the skill: if a number in the draft can't be traced to the source data, the post doesn't ship. The skill enforces the rule even when I forget it exists.

You don't need a Python script. A guardrail can be as simple as a body line — "every stat must cite a source or be deleted" — followed by a final self-check step. The point is that the rule lives in the skill, firing every run, instead of in your head, firing whenever you happen to remember.

Three traps that kill first skills

1. The description describes the body. The single most common reason a skill never fires. Rewrite it as a when, not a what. (See above — this is 90% of the battle.)

2. The skill does too much. If you can't write a one-sentence trigger for it, it's two skills wearing a trenchcoat. Split it.

3. No guardrails. A skill with no checks will reproduce your worst day, flawlessly, on schedule. Add at least one verification step before anything irreversible (a commit, a push, a send).

One honest note on portability

The skill I keep referencing actually runs on OpenClaw, not Claude Code. I'm not hiding that — I'm pointing at it on purpose. Skills follow the Agent Skills open standard, so the same SKILL.md shape (frontmatter router + markdown runbook) works across Claude Code, Codex CLI, Gemini CLI, and Cursor. Learn it once; it travels.

Bottom line

• A skill is a SKILL.md: a frontmatter router plus a markdown runbook.
• The description decides when it fires — write it as a condition ("use when…"), never as a summary.
• Put your guardrails inside the skill so your past mistakes can't re-run.

Write the description last-thing-first, keep each skill to one job, and give it a check it can't skip. Do that and Claude Code stops being a thing you re-explain — and starts being a thing that already knows.

2026.06.02