Claude Operator: Prompt to Autonomy · 20 min · 140 XP
Writing a minimal SKILL.md
The smallest skill that works, and the two ways it gets invoked.
A skill is a directory with a SKILL.md in it. The frontmatter carries the description that decides when it loads; the body is the instructions Claude follows once it has.
--- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. --- ## Current changes !`git diff HEAD` ## Instructions Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.
Two things are worth noticing. The description names the situations that should trigger it, in the words a person would actually use. And the !`git diff HEAD` line runs a command and substitutes its output before Claude sees the skill — so the instructions arrive with the current diff already in them, rather than asking Claude to go and fetch it.
There are two ways in. Automatic discovery: you describe your situation, and the description matches. Explicit invocation: you name the skill directly. Test both. If automatic discovery doesn't fire on a request that obviously should match, the description is the thing to fix — and the fix is usually adding the words a person would really use, not making the description longer or more formal.
Both routes should run the same workflow. If naming the skill gives a noticeably better result than describing the situation, something in the body depends on how it was invoked, and that's a bug you'll hit later when you've forgotten it exists.
Practice. Build a small skill with valid frontmatter, a clear purpose, its inputs, its steps and its output, and confirm it produces the promised result on a sample request. Trigger it without naming it, by describing your situation the way you naturally would. Then invoke it explicitly by name and compare the two results — they should run the same core workflow.
Loading your workspace…