Checking a skill before you trust it
A broken skill does not raise an error. It sits there, never being chosen, while you assume Claude ignored you.
Four things break a skill quietly: no frontmatter, a description over the limit, a name over the limit, and a body with no actual steps in it. All four are checkable, and the panel beside this checks them.
Run it
The file being checked is the skill from lesson 11. Press Run.
"""Check a skill before you trust it.
The two frontmatter fields are what Claude reads when deciding
whether a skill applies, and both have limits: 64 characters for
the name, 200 for the description. A skill that breaks the shape
fails quietly by never being chosen.
"""
text = open("skill.md").read()
fields = {}
body = text
if text.startswith("---"):
end = text.find("\n---", 3)
for line in text[4:end].splitlines():
if ":" in line:
key, value = line.split(":", 1)
fields[key.strip()] = value.strip()
body = text[end + 4:]
name = fields.get("name", "")
description = fields.get("description", "")
steps = [l for l in body.splitlines() if l.strip()[:2] in
("1.", "2.", "3.", "4.", "5.", "6.", "7.", "8.", "9.")]
print("name: ", len(name), "of 64 characters")
print("description:", len(description), "of 200 characters")
print("numbered steps:", len(steps))
print()
if not fields:
print("BROKEN: no frontmatter, so the whole file is treated as content.")
if not name:
print("MISSING: no name.")
elif len(name) > 64:
print("TOO LONG: the name is over 64 characters.")
if not description:
print("MISSING: no description, so Claude has to guess when this applies.")
elif len(description) > 200:
print("TOO LONG: the description is over 200 characters.")
elif " when " not in description.lower():
print("WEAK: the description says what this does but not when to use it.")
if not steps:
print("VAGUE: no numbered steps. A skill is a procedure, not an essay.")
if not any(w in body.lower() for w in ("stop", "ask")):
print("RISKY: nothing tells it what to do when the input is not as expected.")Both fields are inside their limits and the body has six numbered steps, so nothing is reported. The interesting part is the last check, which is not about the format at all: it looks for a line telling the skill what to do when the input is not what it expected. A procedure without that will keep going into work it should have stopped for.
The mistake that accounts for most dead skills
The frontmatter has to start on the very first line of the file. A blank line, a comment or a heading above it and the whole file is treated as content, the fields never exist, and the skill is never matched. Nothing warns you.
Then test it for real
- Ask for the job in a colleague's words and see whether the skill is picked.
- Give it a file that breaks one of its rules and check that it stops rather than guessing.
- Read what it produced against the steps you wrote. A step that gets skipped is usually a step written as prose rather than as an instruction.
skill.md and run it once more. Both are mistakes people make on their first skill.- Paste your own skill into the panel and run the checker over it.
- Add a stop-and-ask line to your skill if the checker says it is missing.
Slow is fine. Stopping is the only problem.