🎯 Capture the intent
skill-creator starts by understanding the intent before writing a single line. If the conversation already contains the workflow the person wants to capture (they say "turn this into a skill"), first extract it from earlier messages — the tools used, the sequence of steps, the corrections they made, and the input and output formats that appeared. Only then ask them to fill in the gaps, and confirm before proceeding.
What does this skill enable Claude to do?
The core capability. Not "help with spreadsheets," but "calculate profit margin and add the column in an xlsx."
When should it trigger?
Which user phrases and contexts trigger the skill. This becomes the heart of the description.
What’s the expected output format?
One file? A report with fixed sections? Code? Defining this early prevents rework.
Worth putting together test cases?
Skills with objectively verifiable output (transforming a file, extracting data, generating code) benefit from tests. Subjective output (style, art) usually doesn’t need them. Suggest the default and let the user decide.
💡 Watch the jargon
skill-creator is used by people with very different levels of technical familiarity. Terms like "JSON" and "assertion" should appear without explanation only when there are clear signs the person knows them. When in doubt, define the term in a short sentence.
🔎 Interview & Research
With the intent captured, go deeper. Proactively ask about edge cases, input and output formats, example files, success criteria, and dependencies. Wait to write test prompts only after finishing this part — a poorly conducted interview creates a skill that covers the happy path and breaks everywhere else.
✗ Shallow interview
- ✗Assumes there’s only one input format
- ✗Ignores what happens with empty or malformed input
- ✗Never asks for real example files
- ✗Doesn’t define what counts as "success"
- ✗Puts the research burden on the user
✓ Interview that sets the stage
- ✓Maps all plausible in/out formats
- ✓Explore edge cases before coding
- ✓Collects concrete examples from the domain
- ✓Establishes explicit success criteria
- ✓Parallel research via subagents/MCPs
Arrive with context ready
Check which MCPs are available. If any could help with the research — finding docs, similar skills, or best practices — research in parallel using subagents (when available) or inline. The goal is to reduce friction for the user: come with the homework done instead of asking everything from scratch.
📝 Write the SKILL.md
Based on the interview, fill in the file components. SKILL.md is YAML frontmatter (with name e description required) followed by the Markdown body.
The components
- •name: the skill identifier
- •description: what it does AND when to use it. It’s the primary trigger mechanism — every “when to use” belongs here, not in the body.
- •compatibility: required tools/dependencies (optional, rarely needed)
- •the rest of the skill :) — the body with the instructions
Description should be a little "pushy"
Today Claude tends to sub-trigger skills — not using them when they would be useful. To combat this, the description needs to list concrete use cases, even when the user doesn't explicitly ask.
Weak vs. pushy:
# Fraca description: How to build a simple fast dashboard to display internal Anthropic data. # Pushy description: How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'
🎯 Anatomy reminder
Progressive disclosure in 3 levels: (1) name+description metadata always in context (~100 words); (2) SKILL.md body when triggered, ideally <500 lines; (3) bundled resources loaded on demand. The description is the trigger.
✍️ Writing style
How you write the skill body matters as much as what you write. Prefer the imperative, use theory of mind and explain the why each instruction instead of stacking MUSTs in all caps. Keep the skill general, not tied to specific examples.
✗ Heavy-handed style
- ✗"ALWAYS do X. NEVER do Y." in all caps
- ✗Rigid rules with no reason
- ✗Instructions tied to a single example
- ✗Treat the model as a blind executor
✓ Style that respects the model
- ✓Clear imperative: "Start by understanding..."
- ✓Explain why each step matters
- ✓Generalizes to many cases
- ✓Uses theory of mind: bets on intelligence
Why avoid shouting MUSTs
Today’s LLMs are smart: they have good theory of mind and, with a good harness, go beyond rote instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using highly rigid structures, that’s a yellow flag—rephrase it by explaining the reason so the model understands why it matters. It’s more human, more powerful, and more effective.
👀 Draft and reread with fresh eyes
Don’t get stuck trying to find the perfect draft. Write a first draft, then reread with fresh eyes and improve. The draft → review → improve cycle happens during the writing itself, even before any testing.
Write the draft
Get everything down on paper without editing. Speed first, polish later.
Reread from a distance
Read it as if you were someone else. What’s ambiguous? What makes the model waste time?
Improve
Cut redundancy, rephrase what was too rigid, explain the reasoning behind what was vague.
💡 Tip
skill-creator repeats this advice in several places: "write a draft, then look at it with fresh eyes to improve it." This applies to the entire SKILL.md and to every future review in the iteration loop.
📦 When to bundle
Not everything lives inside SKILL.md. Bundled resources (scripts/, references/, assets/) load on demand. The rule of thumb: if 3 runs repeat the same script, extract into scripts/; large docs go in references/.
Anatomy of a skill:
skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name, description) │ └── Markdown instructions └── Bundled Resources (optional) ├── scripts/ # código p/ tarefas repetitivas ├── references/ # docs carregadas sob demanda └── assets/ # templates, ícones, fontes
Signs it’s time to bundle
- •3 independent invocations wrote the same thing
create_docx.py→ becomescripts/and tell the skill to use it - •The SKILL.md body is close to 500 lines → add a hierarchy layer with clear pointers
- •Large reference doc (>300 lines) → include an index/TOC
- •A skill supports multiple domains → organize by variant in
references/(aws.md, gcp.md, azure.md)
🎯 Why bundle a repeated script
Write it once, put it in scripts/ and pointing the skill to it saves every future invocation from reinventing the wheel. Scripts run without having to load all the content into context—they’re faster, more reliable, and reusable across iterations.
✅ Module Summary
Next:
4.2 — 🔁 Test, Evaluate, and Iterate — write realistic test prompts, run with-skill vs. baseline, evaluate, and iterate until the skill works well beyond the examples.