Anatomy of a great SKILL.md

The frontmatter fields

---
name: israeli-id-validator
description: Validate Israeli national ID numbers (תעודת זהות) using the Luhn-style check-digit algorithm. Use when a user pastes a 9-digit ID and asks "is this valid", or when generating sample IDs for testing. Do NOT use for foreign passport numbers or business registration numbers.
license: MIT
---

• name must be kebab-case, must match the folder name exactly, and is the slug the LLM uses to identify the skill internally. Pick something specific: israeli-id-validator, not id-tools. Required by the spec.
• description is the single most important field in your skill. In hosts that use description-based routing (Claude Code's skill discovery is the canonical case), the LLM reads primarily this field to decide whether to load the skill into context. In other hosts the user explicitly picks the skill from a list, but the description is still what the LLM sees first. Treat it as both marketing copy and a routing specification. Required by the spec.
• license is typically MIT. The Anthropic upstream spec treats license as conventional rather than strictly required, but the skills-il catalog and most ecosystem tooling expect it. Include it.

The description is the routing input

In hosts that auto-discover skills by description (Claude Code is the canonical case), the LLM scans the descriptions of available skills to decide which (if any) to load. It does NOT read the body. It does NOT read the references/. It reads only the description. In hosts where the user explicitly picks a skill from a list (Claude Desktop, some Cursor flows), the description is still the user-facing summary that determines whether they click. Either way, the description has to:

1. Name the task clearly (in both languages of the term, if there's an Israeli-context name)
2. Trigger on the natural-language patterns a user would actually use
3. Exclude cases that look similar but require a different skill

The "Use when..." and "Do NOT use for..." patterns make this concrete:

"Validate Israeli national ID numbers (תעודת זהות) using the Luhn-style check-digit algorithm. Use when a user pastes a 9-digit ID and asks 'is this valid', or when generating sample IDs for testing. Do NOT use for foreign passport numbers or business registration numbers."

The "Do NOT" clause is critical. Without it, the LLM might load this skill when the user asks about a Romanian passport, then try to apply the Israeli check-digit algorithm and fail confusingly. With the "Do NOT" clause, the LLM correctly routes elsewhere.

Body structure: scope, rules, examples, anti-patterns

The body is what the LLM reads after deciding to load the skill. It needs four sections, in roughly this order:

1. Scope (one paragraph): what exactly this skill covers, restated more precisely than the description allowed.
2. Decision rules (the meat): the if-then logic the LLM should apply. Use bulleted lists, decision trees, or worked examples. Avoid prose.
3. Worked examples (mandatory): show the input, the reasoning, and the output. Cover the typical case and at least one edge case. Without worked examples, the LLM hallucinates the boundary behavior.
4. Anti-patterns (recommended): tell the LLM what NOT to do, even if it sounds tempting. Anti-patterns prevent failure modes that would otherwise look correct.

Study example: israeli-id-validator

Install israeli-id-validator (npx skills-il add developer-tools/israeli-id-validator) and read the SKILL.md. It is a small focused skill (~150 lines) with a clear scope, a deterministic algorithm in scripts/, and concrete worked examples. It is the cleanest reference for "what a small first-skill should look like."

The most common mistake in Chapter 2: writing a description that is too vague. "A skill for Israeli things" gets loaded for every Israeli-context conversation and does nothing useful for any of them. Pick ONE task. Name it specifically. Add the "Use when..." and "Do NOT use for..." patterns.