A SKILL.md example that Claude will actually trigger
A skill file has two jobs: get picked at the right moment, and then say exactly what to do. This one does neither. Here is why, and the fixed version.
The prompt below is one we wrote to show the pattern. It is not a user’s prompt. The verdict, burns, and rebuild were written by us in the roast voice, not produced by the tool.
--- name: release-notes description: Helps with release notes. --- Use this skill when the user wants release notes. Look at the changes and write good release notes. Make them clear and useful. Follow best practices. Include the important stuff and leave out the noise.
Indictment: Your description is four words, and it's the only part Claude reads before deciding whether to open the file.
“description: Helps with release notes.”
The description is the trigger. Claude matches the user's ask against it before loading anything else, and “helps with” matches nothing anyone actually types.
swap: “Helps with release notes.” → “Writes user-facing release notes from a git log, PR list, or diff. Use when asked for release notes, a changelog, or what shipped.”
Write the description as the sentence that decides whether the skill loads: what it does, from what input, and the words people use to ask for it.
“Look at the changes”
Which changes, from where? A git range, a list of PR titles, a pasted diff, and a Jira export all count as “the changes,” and each one needs different handling.
add: an input contract: what the user pastes or which command to run to get the change list, and what to do if neither is present
Name the input. A skill that starts from an undefined noun starts by guessing.
“Follow best practices. Include the important stuff and leave out the noise.”
A rule that can't be broken can't be followed. Nobody can tell whether a draft obeyed “best practices,” least of all the model writing it.
swap: the slogans → the actual rules: group by user impact, breaking changes first, one line per change, skip refactors and dependency bumps unless they change behavior
Replace every quality adjective with the checkable rule it stands for.
--- name: release-notes description: Writes user-facing release notes from a git log, PR list, or diff. Use when asked for release notes, a changelog, "what shipped", or a summary of changes for customers. --- # Release notes ## When to use The user asks for release notes, a changelog entry, or a customer-facing summary of what changed in a release. ## Input One of, in order of preference: 1. A git range the user names (run `git log --oneline <range>`). 2. A pasted list of PR titles or commit messages. 3. A pasted diff. If none is present, ask for the range or the list. Do not write notes from memory of the codebase. ## Steps 1. Read every change. Drop anything with no user-visible effect: refactors, dependency bumps, CI, test-only changes, typo fixes in code comments. 2. Group what remains: Breaking changes, New, Improved, Fixed. Omit empty groups. 3. Write one line per change, starting with what the user can now do or no longer has to do. Name the feature as the user sees it, not the internal component. 4. For breaking changes, add a second line: what to change and by when. ## Output Markdown. A version heading (ask for the version if not given), then the groups above. Lines under 20 words. No adjectives like "exciting" or "seamless". No internal ticket numbers unless the user asks for them. ## Example Input: "feat: add CSV export to reports (#412)", "fix: timezone off by one in scheduler (#415)", "chore: bump eslint" Output: ## v2.4.0 ### New - Export any report as CSV from the report menu. ### Fixed - Scheduled jobs no longer run an hour early in timezones east of UTC.
A Claude skill is loaded in two stages. The description is read first, every time, when Claude decides which skills apply to the request. The body is read only after the skill is chosen. So a weak description means the skill never fires, no matter how good the body is, and a vague body means it fires and then improvises.
The fix is structural, not clever: a description written as the sentence that decides whether to load the file, an input contract so the skill knows what it is working from, numbered steps, and an output format with an example. That shape is what turns a note-to-self into an instruction Claude can follow the same way every time.
- What is a SKILL.md file?
- A markdown file with YAML front matter that packages instructions for Claude around one task. The front matter holds the skill's name and a description Claude uses to decide when to apply it. The body holds the instructions, which are loaded only after the skill is selected.
- What should the description in a SKILL.md contain?
- What the skill does, what input it works from, and the phrases people use when they need it. It is a matching key, not a summary, so include the concrete words a user would type, such as changelog or what shipped.
- How long should a Claude skill be?
- As long as the steps need and no longer. A few hundred words with an input contract, numbered steps, an output format, and one example covers most tasks. Put long reference material in separate files the skill points to rather than in the body.
Paste your own Claude skill file. Get it roasted.
Meerkat reads it, names every problem, and rebuilds it sharp. Free. No signup.
- custom GPT instructionsA custom GPT instructions template that actually holds up
- support agent system promptA customer support agent system prompt that knows when to stop
- business review prep promptA business review summary prompt that survives the executive reading it
- AGENTS.mdAn AGENTS.md example that tells the agent what your conventions are