The ten settings at the top of a skill (and the seven that won’t travel)

At the Claude Code Community Brisbane meetup in September, Tim Sheehan, CTO at The Code Company, built a skill live. He worked from a list of ten settings that sit at the top of the skill file, in a short block called the frontmatter. We have written 25 skills in our own firm, and I still came away with things we had been getting wrong.

Why the top of the file matters

A skill is a folder with a file called SKILL.md in it. The body of that file is the procedure. The frontmatter is the handful of lines above it that tell Claude what the skill is called, when to reach for it and how to run it. Get the body right and the frontmatter wrong, and the skill either never fires or fires when it shouldn’t. To the person using it, both look like “the AI doesn’t work”.

The ten

Name (name). The command people type. Tim flagged a terminology trap here, and he was right to. In Claude Code the folder name is the skill’s name by default, and this field only overrides it. The open Agent Skills standard is stricter: the two must match. Keep them identical and the question never comes up.

Description (description). The most important line in the file. When a session starts, Claude reads only the name and description of every skill and decides from those alone whether one is relevant. The body loads only once a skill is chosen. So the description has to say what the skill does and when to use it, in the words your people actually use. Put the main use case first, because long descriptions get cut short when there are many skills competing for space.

Compatibility (compatibility). What the skill needs to run: a product, a tool, network access. Most skills don’t need it.

Arguments (arguments) and argument hint (argument-hint). Arguments let someone type /fix-issue 123 and have 123 land in the right place in the instructions, by name rather than position. The hint is the placeholder text shown while they type, so they know what to pass.

Model (model) and effort (effort). Which model runs the skill and how hard it thinks. A formatting skill can run on a smaller, faster model at low effort. A review skill can ask for more.

Context (context) and agent (agent). Set context to fork and the skill runs as a separate subagent, of the type named in agent, and hands back only its result. Useful for research that would otherwise flood the conversation. The subagent can’t see the conversation, so the instructions have to stand on their own.

Disable model invocation (disable-model-invocation). Claude can no longer decide to run the skill. Only a person typing the slash command can. Use it on anything with a side effect: sending, publishing, deploying. You don’t want Claude deciding to publish because the draft looks finished.

What we would add

The current Claude Code documentation lists a few more worth knowing. user-invocable: false is the reverse of the last one: Claude can draw on the skill as background knowledge, but it drops out of the slash menu. allowed-tools pre-approves the tools a skill needs, for that turn only. when_to_use adds trigger phrases to the description. paths limits a skill to certain files.

The lesson: seven of the ten won’t travel

Here is the part that matters for a rollout. Only three of the ten, name, description and compatibility, are part of the open standard. The other seven are Claude Code only. Upload a skill that uses them to claude.ai, where most of your people will actually meet it, and the upload fails with an error naming the field it didn’t expect.

So decide where a skill will live before you write it. If it is for the whole business through claude.ai, stick to the standard fields. If it is for the people building in Claude Code, use the rest.

Test it like code

The last thing Tim covered was evaluation. Write a handful of realistic prompts with the pass and fail criteria spelt out, run them with the skill and without it, and keep the results as a baseline. When the model underneath changes, run them again. It is a unit test for a procedure, and it is the only way to know a skill still does what its owner signed off on.