Skills: a procedure it can repeat

A skill is a folder with a markdown file in it. The file says how to do one job, and Claude loads it only when that job comes up.

That last part is the reason skills exist rather than more CLAUDE.md. CLAUDE.md is in context all session, every session. A skill's body is loaded when it is used, so you can have twenty of them and pay only for their descriptions until one is needed.

One skill

---
name: release-notes
description: Write release notes from the commits since the last tag. Use when preparing a release or when asked what changed.
allowed-tools: Bash(git log:*) Read
---

1. Find the last tag with `git describe --tags --abbrev=0`.
2. Read `git log <tag>..HEAD --oneline`.
3. Group the commits into Added, Fixed and Changed.
4. Write one line per entry, in plain language, no commit hashes.
5. Leave out anything that only touched tests or formatting.

The frontmatter is the interface. name is what you type after a slash, and it defaults to the folder name. description is what Claude reads when deciding whether this skill applies to what you just asked. allowed-tools lists what it may use without stopping to ask, for the turn that invoked it.

The body is a numbered procedure, and it reads like instructions to a person who is capable but new. Not an essay about release notes: the actual steps, in order.

The description does the routing

Say what changed since the last release? and Claude picks this skill because the description mentions release notes and when to use them. A description like release notes helper would not have been enough. This is the same lesson as tool descriptions: the words are the interface.

If you would rather it never fired on its own, set disable-model-invocation: true and it only runs when you type /release-notes.

Check it before you trust it

A broken skill fails quietly: it simply never gets picked, and you assume Claude ignored you. The panel beside this runs a checker over the skill file above. Press Run.

"""Check a SKILL.md before you trust it.

Three things decide whether a skill is ever used: valid
frontmatter, a description that says when to use it, and a
body short enough to be cheap.
"""

skill = open("SKILL.md").read()


def frontmatter(text):
    if not text.startswith("---"):
        return {}, text
    end = text.find("\n---", 3)
    head, body = text[4:end], text[end + 4:]
    fields = {}
    for line in head.splitlines():
        if ":" in line:
            key, value = line.split(":", 1)
            fields[key.strip()] = value.strip()
    return fields, body


fields, body = frontmatter(skill)
lines = [l for l in body.splitlines() if l.strip()]

print("name:       ", fields.get("name", "(the folder name)"))
print("description:", len(fields.get("description", "")), "characters")
print("body:       ", len(lines), "non-empty lines")
print()

if not fields:
    print("PROBLEM: no frontmatter. The whole file is content.")
if "description" not in fields:
    print("PROBLEM: no description, so Claude has to guess.")
elif len(fields["description"]) < 40:
    print("WEAK: it says what this is, not when to use it.")
if len(lines) > 40:
    print("HEAVY: this body loads whenever the skill runs.")
if not any(l.strip()[:1].isdigit() for l in lines):
    print("VAGUE: no numbered steps. A skill is a procedure.")

The frontmatter has to start on the very first line of the file, or the whole thing is treated as content and none of the fields exist. That single mistake accounts for most skills that do nothing, and it is the first thing the checker looks for.