What makes a good skill

Three ways to teach an agent, three different triggers:

• Memory file (CLAUDE.md, AGENTS.md) — always loaded, every session, every turn. For rules that should never be off.
• Slash command — runs when you call it. For things you want on demand, exactly when you say so.
• Skill — the agent decides it's relevant and loads it. For repeatable processes you'd otherwise have to remember to ask for.

The skill's superpower is the middle ground: it's not a per-turn tax like a memory file, and it doesn't depend on you remembering it exists like a command. It sits on the shelf with a one-line label, and the agent reaches for it when the task matches the label.

Good candidates share a shape:

• A process you've repeated. Code reviews, release checklists, meeting processing, deploys, "new project" setup. If it saved you time twice, it'll save someone else the third time.
• Rules the model can't guess. Your house voice, your commit format, your "never touch the dev database" rails. A skill is how the agent stops re-learning your taste.
• Checkable steps. Commands that run, output you can eyeball, a definition of done. "Make it better" is a wish; "run these five checks and report what fails" is a skill.
• A trigger you can finish in one sentence. "Use this when the copy reads like a model wrote it." If you need "and sometimes also…", it's probably two skills.
• Self-contained. Everything the agent needs — steps, templates, helper scripts — lives in the skill's folder.

And what doesn't belong:

• One-off tasks. Just ask. A skill you trigger once is a prompt with extra filing.
• Things the model already does well unaided. A skill that adds nothing is context that costs something.
• Project-specific facts ("our staging URL is…"). Those belong in the project's AGENTS.md, not in a shared skill.
• Always-on rules. If it should never be off, it's memory-file material — don't make the agent guess when to load it.
• Mega-workflows. A 12-phase epic procedure becomes a skill nobody's agent can wield. Split it into small skills that chain.

A real one, from the exchange — de-ai-ify, which rewrites AI-sounding copy into a plain human voice:

---
name: de-ai-ify
description: Rewrite copy to strip the tells of AI-generated writing
  and land a warm, concrete human voice — plain words, short
  sentences, specifics over adjectives.
---

# De-AI-ify

Use this on any prose that reads like a model wrote it…

## The target voice      ← what "good" looks like, named concretely
## Kill list             ← checkable rules the agent can sweep for
## Rules                 ← constraints it must not break
## Before / after        ← examples: show, don't describe

The description line does the triggering. It's the only part the agent sees before deciding to load the skill, so spend your words there: what it does, and when to reach for it. "Helps with writing" loads never. "Rewrite copy to strip the tells of AI-generated writing" loads exactly when it should.

The body is the procedure. What good looks like, the steps, the rules, and — most valuable of all — examples. One before/after pair teaches more than three paragraphs of advice, and costs fewer tokens every time it fires.

Keep it to a page. The whole file enters the context window when the skill fires. If it needs reference material, put it in a sibling file in the same folder and point to it — the agent can open it only when the task needs it.

You don't write a skill from a blank page. You describe the process the way you'd explain it to a new hire, and the agent shapes it. Paste this into a session, fill in the brackets:

Write a SKILL.md for an agent skill.

Name: [short-kebab-name]
What it should do: [the task, in your words]
When it should trigger: [the situations, in one sentence]
Rules it must never break: [your constraints]

Here's how I do it by hand:
[paste your steps, an example, whatever you have —
 messy is fine]

Draft it with frontmatter (name, description). The description is
one sharp line saying what it does and when to reach for it — it's
what the agent reads to decide whether to load the skill, so make it
count. Ask me whatever you need to know before writing.

Two moves make this work: answering its questions honestly (the gaps it asks about are the gaps in your process), and pasting one real example of the finished work. "Make it sound like this" beats every adjective you were about to type.

Then test the trigger. Drop the folder into ~/.claude/skills/, start a fresh session, and describe the task without naming the skill. If the agent doesn't pick it up, the description is too vague — sharpen it and try again. If it fires when it shouldn't, say what it's not for in the description. Two or three rounds and it settles.

The house rule: adopt one, improve one. Take a skill into your setup, and send one PR that makes something in the library better — a sharper description, a missing rule, a new skill. Knowledge multiplies or it evaporates.