How to Write a Claude Code Skill (SKILL.md) That Actually Triggers

The most common complaint about Claude Code skills isn't that they're hard to write — it's that they never fire. You write a careful SKILL.md, ask Claude to do exactly the thing it covers, and watch it improvise from scratch instead. Nine times out of ten the skill body is fine and the problem is one field: the description. This guide covers how triggering actually works, and how to write skills that reliably activate.

How skill triggering actually works

Skills use progressive disclosure. Claude does not read your whole skill library — at the start of a session it sees only each skill's name and description from the YAML frontmatter. When a request comes in, Claude compares the task against those descriptions and loads the full SKILL.md only when one matches.

This has a blunt implication: the description is not documentation — it is the trigger. Claude decides whether to load your skill based on those one or two sentences alone. The 400 lines of expertise below the frontmatter play no part in the decision. A brilliant skill with a vague description is invisible.

The anatomy of a SKILL.md

---
name: api-conventions
description: REST API conventions for this codebase. Use when
  creating or modifying API endpoints, routes, controllers, or
  request/response handling — covers validation, error format,
  auth middleware, and naming.
---

# API Conventions

## Endpoint checklist
1. Validate input with zod schemas in src/schemas/
2. Errors use the ApiError class — never raw strings
...

The name must be lowercase letters, numbers, and hyphens (max 64 characters). The description has a hard budget (around 1024 characters) — but the real budget is attention, so aim for one to three dense sentences.

The description formula: what + when

Every reliable description answers two questions:

• What does this skill do? One clause, concrete.
• When should it be used? The trigger conditions, phrased in the words a user would actually type.

Compare:

# ❌ Never fires
description: Helps with PDFs.

# ❌ Fires at the wrong times
description: A comprehensive document processing solution
  for enterprise workflows.

# ✅ Fires reliably
description: Extract text and tables from PDF files, fill
  PDF forms, merge or split documents. Use when the user
  mentions PDFs, forms, or document extraction.

The third version works because it contains the actual vocabulary of the task — "PDF", "forms", "merge", "extract". Claude matches your description against the user's request, so the description should sound like the requests it's meant to catch.

Five reasons skills don't trigger (in order of frequency)

1. Vague description. "Helps with data" matches everything, so it effectively matches nothing. Fix: name the file types, verbs, and domain words.
2. Missing "use when" clause. The skill says what it does but not when to reach for it. Fix: add explicit trigger phrasing — "Use when the user asks to…" followed by realistic requests.
3. Written in first person or marketing voice. Descriptions are read by the model in third person. "I can help you with spreadsheets!" matches worse than "Reads, edits, and creates .xlsx spreadsheets."
4. Overlapping skills. Two skills with similar descriptions compete, and the wrong one wins — or neither does. Fix: give each skill a distinct territory and name the boundary in both descriptions ("for Word documents, not PDFs").
5. Broken frontmatter. Bad YAML (tabs, unquoted colons, missing --- fences) means the skill silently fails to load at all. Fix: lint it — our free SKILL.md validator catches exactly this.

Writing the body: instructions for a colleague, not an essay

Once triggering works, the body determines whether the skill helps. Principles that hold up:

• Keep SKILL.md under ~500 lines. Move deep reference material into separate files in the skill folder and link them — Claude reads them on demand. Progressive disclosure applies inside the skill too.
• Prefer checklists and steps over prose. "1. Run the schema validator. 2. If it fails, fix before proceeding" beats three paragraphs of context.
• Include one worked example. A single before/after or sample output anchors the format better than any amount of description.
• State what not to do. Skills exist because Claude's default behavior wasn't what you wanted — say so explicitly. "Never edit generated files in dist/" is a sentence; debugging its absence is an afternoon.
• Ship scripts for deterministic work. If a step is mechanical (convert, validate, scaffold), include a script in the folder and have the skill run it, rather than having Claude re-derive the logic each time.

Test it like code

Don't declare victory after writing the file. Open a fresh session and phrase your request the way a teammate would — without naming the skill. If it fires, try two more phrasings. If it doesn't, ask Claude directly: "Which of your available skills would you use for this request, and why?" The answer usually points straight at the description flaw. Iterate on the description like you'd iterate on a failing test.

FAQ

Keep reading