Best practices for skills that work
A skill can be perfectly written inside and still never trigger, or trigger when it shouldn't. These are the principles that separate a skill that works from one Claude ignores. SkillCreator applies them for you, but knowing them will help you write better skills.
1. The description rules
Claude doesn't read the inside of all your skills on every message: it reads the name and the description, and decides which to use from that. So the description must contain both: what the skill does and when to use it. Write it in the imperative («Use this skill when…») and be a little pushy: list several situations and include cases where the user doesn't name it explicitly. It's the best defense against under-triggering (the skill exists but never fires). There's a dedicated guide on how to write good descriptions.
2. Imperative instructions — and explain the why
Give orders directly: «Check…», «Write…», «Verify…». And when an instruction matters, explain why. Today's models follow a rule better when they understand the reason than when they get an all-caps «ALWAYS» or «NEVER» with no context. «Don't apply changes without reviewing them first, because a production error affects real users» works better than «NEVER apply without reviewing».
3. Examples teach more than rules
A good input-and-output example teaches Claude the expected result better than a paragraph of instructions. Use the «Request → Result» pattern with realistic cases. Two or three well-chosen examples are worth more than ten abstract rules.
4. Define the output format
If your skill should always return a result with the same structure (a report, a template, fixed sections), define it explicitly with a template. That way the result is consistent every time. SkillCreator has a dedicated block for this.
5. Progressive disclosure: keep the skill light
The body of the skill should be concise. Heavy material —long documentation, reference tables, scripts— goes in separate folders (references/, scripts/) that Claude consults only when it needs them. That keeps the context light and the skill fast. It's what Anthropic calls «progressive disclosure».
6. One skill, one capability
Each skill should do one thing well. If you try to cram three different tasks into one, the description becomes fuzzy and Claude won't know when to trigger it. If you need several capabilities, create several skills.
7. A correct name
The name is lowercase, with hyphens and no accents (for example csv-analyst), with a maximum of 64 characters. SkillCreator formats it for you automatically.
The good news: you don't have to remember all this
The SkillCreator wizard already applies these principles: it scores your description live, structures the SKILL.md in the correct format, offers an output-format block and validates the name. You bring the idea; we bring the best practices.