AI AI Tools Guidebook
AI Tool Tutorials

Claude Skills Walkthrough: How a Skill Actually Fires (2026)

Skills look like a toggle but behave like a matcher. Here is exactly how Claude reads a SKILL.md description and decides to fire, with the limits and fixes.

Published: Updated: Author: AI Productivity Guide Team 🌐 查看中文版本

A Claude Skill is not a checkbox. It is a folder with a SKILL.md file: a short YAML header (a name and a description), a markdown body of instructions, and optional scripts and reference files. Skills shipped in October 2025 and are now the standard way to give Claude a repeatable capability across claude.ai, Claude Code, and the Claude API. The thing nobody tells you up front: whether a Skill fires depends almost entirely on one field — the description — because that is the only part Claude reads before every reply.

This walkthrough traces what happens between your message and the Skill running, names the exact limits that bite you, and gives the fixes for the most common failure (a Skill that never triggers).

TL;DR

  • Claude pre-loads only the name + description of every installed Skill into the system prompt — roughly 100 tokens per Skill — then reads the rest of SKILL.md only after a match. This is Anthropic’s “progressive disclosure” model.
  • The description is the trigger. Hard limits (as of June 2026): name max 64 characters (lowercase, numbers, hyphens, no “anthropic”/“claude”); description max 1024 characters, written in third person.
  • If a Skill never fires, the description is the bug 90% of the time. Fix the description before touching the instructions.
  • Keep the SKILL.md body under 500 lines; push anything longer into reference files that load on demand.
  • Skills do not sync across surfaces. A Skill uploaded to claude.ai is not on the API or in Claude Code, and vice versa.

How loading actually works: three levels

Anthropic structures Skills so they cost almost nothing until they are relevant. As of June 2026 the docs describe three loading levels:

LevelWhat loadsWhenToken cost
1. Metadataname + description from the YAML headerAlways, at startup~100 tokens per Skill
2. InstructionsThe full SKILL.md bodyWhen the Skill is triggeredUnder ~5k tokens
3. ResourcesBundled reference files and scriptsOnly when Claude reads/runs themEffectively unlimited (zero until accessed)

This is why you can install dozens of Skills without bloating context: at rest, Claude only knows each Skill exists and when to use it. The body and any reference/ files stay on the filesystem until a match pulls them in via bash. Scripts are even cheaper — Claude runs them and only the output enters context, never the source.

The practical consequence: your Skill lives or dies on the ~100 tokens in the header. If the description does not signal the right trigger, Claude never reaches Level 2, so your beautifully written instructions are invisible.

The exact constraints (June 2026)

These are validation rules from Anthropic’s Agent Skills docs, not folklore:

  • name: max 64 characters; lowercase letters, numbers, and hyphens only; no XML tags; cannot contain the reserved words “anthropic” or “claude”. Anthropic recommends gerund form, e.g. processing-pdfs, analyzing-spreadsheets.
  • description: non-empty, max 1024 characters, no XML tags, written in third person. It must state both what the Skill does and when to use it.
  • SKILL.md body: keep under 500 lines for reliable performance; split overflow into separate files referenced one level deep.

Third person matters more than it looks. The description is injected into the system prompt verbatim, so “I can help you process Excel files” or “You can use this to…” creates a point-of-view clash that hurts discovery. Write “Analyzes Excel spreadsheets, creates pivot tables, generates charts.”

Step by step: build one Skill that fires

  1. Run the task by hand first. Do it in a plain Claude chat (or a Claude Code session) until the prompt is stable. If you cannot prompt it manually, you cannot package it.
  2. Name the action, not the topic. Use gerund form: summarizing-transcripts, not meeting-stuff. Stay under 64 characters.
  3. Write the description as “Does X. Use when [specific trigger/context].” Borrow Anthropic’s own pattern — their PDF Skill reads: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. Pack in the literal keywords a user would actually type.
  4. Write the body like an onboarding note: role, expected inputs, steps, output format, refusal rules. Assume Claude is already smart — only add what it does not know. Keep it under 500 lines.
  5. Add a 2-3 example input/output pair inside the body. Anthropic’s authoring guidance recommends concrete examples over abstract prose; a worked input/output pair tends to make the Skill fire and behave more reliably than a bare description.
  6. Install it on your surface. claude.ai: Settings > Features, upload the Skill as a zip (Pro, Max, Team, or Enterprise with code execution on). Claude Code: drop the folder in ~/.claude/skills/ (personal) or .claude/skills/ (project). API: upload via the /v1/skills endpoints.
  7. Test with the exact phrasing from your description. If it does not fire, the description does not match — fix the wording before you touch instructions.
  8. Test with a paraphrase you would actually say. If the paraphrase misses, add one or two real synonyms to the description, still in third person. Do not rewrite the body yet.

Why a Skill fails to trigger (and the fix)

Almost every “it never fires” report traces to the header, not the model.

  • Vague description. Helps with documents gives Claude nothing to match. Fix: name the action plus the literal trigger words. Anthropic’s own guidance is that a specific, trigger-ready description is the single biggest lever on activation rate.
  • Topic instead of trigger. About meetings describes a subject, not a moment. Fix: Summarizes meeting transcripts into bullets and action items. Use when the user pastes a transcript and asks for a summary.
  • First/second person. I can help you... clashes with the system prompt. Fix: rewrite in third person.
  • Wrong surface. You uploaded to claude.ai but tested in Claude Code, or built it in Claude Code and expected it on the API. Skills do not sync; install on each surface separately.
  • Two Skills competing. When descriptions overlap, one usually wins by coin flip. Fix: make descriptions disjoint — state what each covers and what it does not.
  • Buried in instructions. Edge cases crammed into the body do not change whether the Skill fires; only the header does. Keep the body lean and the trigger in the description.

First-run exercise

  1. Build one Skill for the smallest weekly task you have — for example, summarizing-transcripts: turn a transcript into 5 bullets and 3 action items.
  2. Fire it 5 times across a week with different inputs. Log each run as auto-fired, name-invoked, or missed.
  3. After 5 runs, edit only the description — not the body. Tightening the trigger words is usually what moves the auto-fire rate.
  4. Hand the Skill to one teammate (re-upload it for them; claude.ai Skills are per-user and do not share automatically) and ask them to use it without coaching. If they cannot trigger it, the description is too internal.

Quality check

  • Did it fire on the natural phrasing in your description? If not, that phrasing is the bug.
  • Is the output shape stable across runs? A Skill that produces five different formats is still a prompt, not a Skill — add a template or an example pair to the body.
  • Did it stay quiet on adjacent-but-different requests? Over-firing erodes trust as fast as under-firing.

Pick one repeating task → run it by hand until the prompt is stable → write the description in “Does X. Use when Y” third-person form with literal keywords → paste the prompt as the body with one example pair → install on your surface → test the exact phrase, then a paraphrase → review fire rate weekly and tune the description first.

FAQ

  • How does Claude decide to fire a Skill? It reads the name + description of every installed Skill (pre-loaded in the system prompt at startup) and matches them against your message. A specific, keyword-rich description in third person is the dominant factor; vague descriptions rarely fire.
  • What are the exact limits on a Skill? As of June 2026: name ≤ 64 characters (lowercase, numbers, hyphens; no “anthropic”/“claude”); description ≤ 1024 characters, non-empty, no XML tags; keep the SKILL.md body under 500 lines.
  • Can I force a Skill by name? In Claude Code you can invoke a Skill explicitly; in claude.ai, naming the Skill in your message strongly biases selection. Useful for testing instructions and for Skills you want users to call deliberately, but day-to-day you want auto-fire from the description.
  • Do Skills sync across claude.ai, Claude Code, and the API? No. Each surface is separate — upload to each one you need. claude.ai Skills are per-user; API Skills are workspace-wide; Claude Code Skills live in your filesystem.
  • Can two Skills fire on one message? Usually one wins. Overlapping descriptions cause a coin flip; write disjoint descriptions that state what each Skill does and does not cover.
  • Where do I put reference files and scripts? Bundle them in the Skill folder and link them one level deep from SKILL.md. They load only when Claude reads them, so a Skill can carry large docs or datasets at zero resting cost.

Tags: #Claude #Skills #Tutorial

Related Articles