Save as .claude/skills/writing-agent-skills/SKILL.md in a repository, or under ~/.claude/skills/writing-agent-skills/SKILL.md to have it everywhere. The copy button takes the whole file, frontmatter included.

---
name: writing-agent-skills
description: Write a SKILL.md that actually fires and actually changes the work. Use when asked to create an agent skill, write a SKILL.md, turn a repeated workflow into a skill, or fix a skill that is being ignored.
---

# Writing agent skills

A skill is a directory containing a `SKILL.md`: YAML frontmatter with a `name`
and a `description`, then markdown instructions. The format takes a minute.
Writing one that earns its place takes judgement.

## Is this worth a skill

Write one when the work repeats **and** involves judgement: an order of
operations, traps that are not general knowledge, a house convention, a format.

Do not write one for:

- A one off. Just ask.
- A capability that does not exist. Instructions cannot reach the network or a
  database. A skill wrapped around a missing capability produces confident
  invention, not an error. That needs a tool or an MCP server.
- A task with one exact answer and no judgement, such as hashing or converting
  a timestamp. Models are unreliable at these and instructions do not fix it.

## The description decides everything

It is the only part always in context, and it is what a request is matched
against. A perfect body behind a vague description never runs.

Write it with both halves: what the skill does, and when to use it.

Use the words a person actually types. They describe symptoms, not diagnoses.
"works in Chrome but curl fails" is a real phrase; "chain validation" is not.

    description: Diagnose TLS and certificate faults on a live host,
      including expiry, incomplete chains and untrusted roots. Use when a
      site shows a certificate warning, a client reports an expired or
      untrusted certificate, or curl fails where a browser works.

Name the specific nouns, because specific terms match specific requests.

## The body

Write instructions, not an essay. Imperative, ordered, concrete.

**Write only what is not already known.** The assistant knows what a
certificate is. It does not know that your internal CA is only on the build
images, or that your deploys fail on the migration step. Skip the teaching.
Write the order, the traps and your conventions.

**Number the steps when order matters**, and say why skipping is harmful.
Ordering is the single most valuable thing most skills contain.

**Write the traps down.** The thing everyone gets wrong is worth more than
three paragraphs of correct background.

**Say what the output should look like.** Put the format near the top, because
instructions at the end of a long file land less reliably.

**Say what not to do.** Negative instructions prevent the confident wrong
answer, which is the expensive failure.

## Keep it small, put the rest beside it

A skill is a directory. Loading works in levels: the name and description are
always in context, the body loads when the skill fires, and bundled files load
only when something reads them.

So keep `SKILL.md` to the decisions, and move reference material into sibling
files one level deep:

    tls-triage/
      SKILL.md
      chain-order.md
      trust-stores.md

Keep the body short. If it is growing past a few hundred lines, something in it
is reference material.

## Declare dependencies

If the skill calls a tool or an MCP server, say so near the top, and say what
to do when it is missing:

    If the lookup tool is unavailable, say so and stop. Do not describe what
    the record probably contains.

Without that line the default behaviour is to be helpful, which means
inventing.

## Test it

1. **Does it fire?** Fresh session, five real phrasings, no hints. If not, fix
   the description, not the body.
2. **Does it stay out of the way?** Three nearby requests that belong
   elsewhere should not trigger it.
3. **Does it change the work?** Run a case where you know the answer. Check it
   followed the order, avoided the trap and used the format.
4. **Does it refuse when it cannot verify?** Remove the tool and check it stops
   rather than inventing.

Keep three or four known cases in a file beside the skill, and rerun them after
every edit.

## Report back

1. The skill, as a complete file.
2. Why the description is worded that way.
3. What you put in sibling files and why.
4. The cases to test it with.