Write A Skill

Write a Skill

A skill is an onboarding guide for an agent: a folder with a SKILL.md that loads on demand and teaches Claude a repeatable behavior. This meta-skill converts "here's what I want" into that document, correctly structured, so the user doesn't need to know the format, the YAML rules, or the triggering mechanics.

The stakes are asymmetric. A skill gets invoked hundreds of times by someone who will never read its source, so an hour of care at authoring time is amortized across every future invocation, and a flaw (a description that never triggers, an instruction that overfits) is paid on every one.

Step 1: Extract the intent

From the user's description, and from the conversation itself if they said "turn THIS into a skill" (mine the thread for the workflow, the corrections they made, the output format they accepted), establish:

1. What behavior should the skill produce?
2. When should it fire: what would the user actually type?
3. When must it NOT fire: the near-miss cases?
4. What does a good output look like: is there a fixed format?
5. Does anything need to be deterministic (a script) rather than generated fresh each time?

Ask only for what's genuinely missing, 3-5 questions at most. The questions about anti-triggers (#3) and output format (#4) are the ones users never volunteer and always have opinions about.

Step 2: Write the frontmatter

Name: lowercase, hyphens, max 64 chars, matching the folder name. Verb phrases or clear nouns: fact-checker, grill-me, not my-cool-skill-v2.

Description: this is the skill's entire interface for triggering. Claude sees only the name + description when deciding whether to load the skill, choosing among potentially 100+ of them. Build it from four parts, in this order:

1. What it does, one sentence, concrete active verbs, third person.
2. Trigger contexts, written pushy, because Claude under-triggers skills by default: "Use this skill whenever the user mentions X, Y, asks to Z, or [implicit situation], even if they don't explicitly say [keyword]."
3. Proactive cases if any: "ALSO use when..." for situations where the user won't ask but the skill should apply.
4. Exclusions: "Do NOT use for..." naming the tempting near-misses. Over-triggering is what makes users uninstall skills, so the exclusions earn their space.

Keep it under 1024 characters. Always write it as a YAML block scalar (description: >-): a plain unquoted description containing a colon followed by a space breaks YAML parsing, and this is the single most common packaging failure.

Step 3: Write the body

Target under 500 lines; under 150 is typical for behavior skills. Use imperative voice. Structure:

# Skill Name

[Opening: 1 short paragraph on WHY this skill exists — what failure
it prevents. This paragraph does real work: it's the rubric Claude
uses for every edge case the rest of the file doesn't cover.]

## Core rule
[The one non-negotiable, if there is one, stated plainly.]

## Workflow
[Numbered steps in execution order. For each step that could be done
lazily or wrongly, attach the reason it matters.]

## Output format
[If output has a fixed shape, show the exact template in a fenced
block. "Use this exact structure" + template beats paragraphs of
format description.]

## Calibration / When NOT to apply
[Both failure directions: what under-use looks like, what over-use
looks like, and which is worse for this skill. A rough threshold.]

## Example
[At least one realistic worked example: plausible messy input, the
skill's actual output. Realistic means typos, buried details, and
context, not a sanitized textbook case.]

Authoring principles that separate great skills from mediocre ones:

• Explain the why, not just the what. "Never paraphrase quotes, because misattribution is the most common quote failure" generalizes; "NEVER paraphrase quotes" doesn't. All-caps MUST/ALWAYS/NEVER strings are a yellow flag: usually a missing explanation.
• Only add what Claude doesn't know. Claude knows what an email is; it doesn't know the user's escalation policy. Every generic sentence costs context that specific sentences could use.
• Generalize past the examples. The skill will run on a million inputs; instructions overfitted to the one example in the file will fail on the other 999,999.
• Density over decoration. Once loaded, every token of the skill competes with the actual conversation.

Step 4: Bundle resources only when earned

• scripts/: for deterministic or repetitive work; scripts execute without loading their code into context, only output costs tokens. Signal: the same helper logic would be regenerated on every run.
• references/: docs loaded only when needed. Split content out of SKILL.md when paths are mutually exclusive (per-framework guides), and tell SKILL.md exactly when to read each file.
• assets/: templates, fonts, boilerplate used in the output.

Most behavior skills need none of these. Don't create empty folders.

Step 5: Validate, package, deliver

Before packaging, check:

1. Frontmatter parses (block scalar description; name matches folder).
2. Description read alone answers "when would Claude pick this?"
3. At least one exclusion case is named.
4. Every rule either states its reason or is self-evident.
5. The example is realistic, not sanitized.

If a packaging script is available (e.g. skill-creator's package_skill), produce the installable .skill; note that output must go to a writable directory, and installed skill locations are often read-only, so copy elsewhere before editing an existing skill. Deliver both the package and the readable SKILL.md, then offer, once, to test with 2-3 realistic prompts.

Worked example

User input: "make a skill that stops me from sending angry emails"

Resulting frontmatter:

---
name: cooldown-check
description: >-
  Intercept emotionally charged messages before they're sent by flagging
  heat markers, predicting recipient reaction, and offering a rewrite
  that keeps the substance while cutting the heat. Use this skill
  whenever the user drafts or asks to send an email, Slack message, or
  reply written in anger or frustration, mentions a conflict with the
  recipient, uses hostile or sarcastic language in a draft, or asks "is
  this too harsh". Do NOT use for deliberately firm messages the user
  has consciously chosen (final warnings, formal complaints), or for
  messages with no emotional charge.
---

Note the moves: the vague wish became concrete behavior (flag, predict, offer rewrite), triggers include situations the user didn't name (sarcasm in a draft, "is this too harsh"), and the exclusion protects deliberate firmness, because a skill that softens a message the user MEANT to be firm would get uninstalled within a week.