Writing Skills

Writing Skills

A skill exists to pull consistent behavior out of a probabilistic model. Every rule below serves that: say only what changes behavior, make it easy to find, keep it easy to read.

This is the shared craft — a lightweight, always-on reference to write a SKILL.md well. For an interactive workshop that scaffolds, runs evals/benchmarks, and optimizes a description, install Anthropic's skill-creator; these principles still apply to what it produces.

For environment specifics, pair this with the matching surface skill: claude-md-and-folder-standards for Claude Code, or authoring-app-skills for the Claude app/Cowork.

Frontmatter

• Required: name (lowercase, hyphens, ≤64 chars, no "claude"/"anthropic") and description.
• The description is the whole discovery mechanism. It's the only part preloaded every session; the model picks this skill from it alone. Write it in third person, and state both what the skill does and when to use it (the triggering conditions). Front-load the distinctive trigger word.

Say only what changes behavior

• Assume the model is already smart. Add only what it would get wrong or can't know.
• No-op test, per sentence: if a line doesn't change behavior versus the default, delete it — don't reword it. "Write clean code" fails. Real conventions, gotchas, and exact steps pass.
• One idea, one home. Duplication across sections (or skills) drifts and rots — link instead.

Progressive disclosure

• The SKILL.md body is the map, not the whole territory. Keep occasional/heavy detail in sibling files and link to them; they cost nothing until read.
• Keep links one level deep from SKILL.md. Nested pointers get partially read and missed.
• Inline what every path needs; push behind a link what only some paths need.

Scope & size

• One workflow or domain per skill. If two distinct triggers want independent firing, that's two skills.
• Keep the body tight — say only what earns its place. Anthropic's ceiling is 500 lines; split to sibling files well before that. Fewer lines that all pass the no-op test beats padding to a limit.

Style that reads reliably

• Match specificity to fragility. Fragile, one-right-way tasks get exact steps; open tasks get direction and trust. Over-specifying an open task is as harmful as under-specifying a fragile one.
• Use one term per concept throughout — consistency helps the model parse.
• Show input→output examples where quality depends on shape; they teach faster than description.
• Steer toward the target behavior, not away from the wrong one. Prohibitions make the banned behavior more salient — prefer stating what to do; reserve "don't" for true guardrails, paired with the positive alternative.
• No time-sensitive phrasing ("after August"). Put superseded guidance in an "old patterns" aside.

Before done

1. Does the description alone tell a cold model what this is and when to fire it?
2. Every remaining sentence passes the no-op test?
3. One domain, links one level deep, no duplication with sibling skills?