How a Skill Comes Together: From Idea to Package
A Skill does not begin with a folder or a YAML file.
//
Search across all documentation pages
A Skill does not begin with a folder or a YAML file.
It begins with a moment of recognition: you notice you have asked Claude to do the same kind of task, the same way, more than once.
That repeated task is the raw material. Packaging is just the last step, not the first.
This page walks through the full path a Skill travels, from noticing the repetition to a working SKILL.md folder Claude can discover and load on its own.
Every Skill starts life as a repeated task: something you have asked Claude to do more than once, in more or less the same way, with more or less the same steps.
Maybe it is drafting a weekly status update from a set of notes. Maybe it is reviewing a pull request against a fixed checklist. Maybe it is converting a customer transcript into a structured summary.
The common thread is repetition with a consistent shape. A task you did once and will never do again is not a good candidate. A task you do differently every time, with no stable pattern, is not a good candidate either.
Once you have identified that pattern, the destination is a Skill package: a folder containing one required file, SKILL.md, and optionally a handful of supporting files alongside it.
my-skill/
SKILL.md # required: frontmatter + instructions
reference.md # optional: extra detail Claude loads only if needed
helper-script.py # optional: a script the instructions can point toSKILL.md itself has two parts: a small YAML frontmatter block at the top, and a body of instructions below it.
---
name: weekly-status-update
description: >-
Drafts a weekly status update from raw notes. Use when the user asks for a
status update, weekly summary, or standup recap based on notes or bullet points.
---The frontmatter is metadata Claude reads to decide whether this Skill is relevant to the task in front of it. The body is what Claude actually follows once it has decided to use the Skill.
That separation is the core idea to hold onto for everything that follows: frontmatter decides whether the Skill loads, and the body decides what happens once it does.
The path from idea to package moves through a small number of stages, each building on the one before it.
Stage 1 - Notice the pattern. Before writing anything, confirm the task really does repeat with a consistent shape. If you cannot describe the steps you take today in a sentence or two, it is too early to package it.
Stage 2 - Write the instructions in plain language first. Describe what you actually do, in order, the way you would explain it to a new teammate. Do not worry about frontmatter or file structure yet. Get the steps right before you get the packaging right.
Stage 3 - Draft the description. This is the single most consequential piece of the whole package. The description field is what Claude compares against a new task to decide whether this Skill applies. It needs to state both what the Skill does and when it should trigger, in concrete enough language that a near-miss task doesn't accidentally match.
Stage 4 - Turn the plain-language steps into numbered instructions. Vague prose ("handle the formatting appropriately") gets rewritten as a specific, ordered step ("apply the house style guide in step 3, then re-check heading levels"). Numbered steps are what let Claude execute the same way every time.
Stage 5 - Decide what tools the Skill actually needs. Some Skills only need to read and reason. Others need to write files, run commands, or call specific tools. This is where allowed-tools comes in, scoping exactly what the Skill may invoke even if it gets triggered in a context you didn't anticipate.
Stage 6 - Add bundled resources, only if they earn their place. If the instructions keep referring to a reference table, a template, or a helper script, that content moves into its own file inside the Skill folder, and the body points to it by name rather than inlining everything.
Stage 7 - Test the trigger, not just the output. Run a task you'd expect to activate the Skill, and a task you'd expect not to, and confirm Claude picks the right one. A Skill that produces a good result is only half the job if it never gets discovered in the first place.
Idea (repeated task)
-> plain-language steps
-> description drafted (what + when)
-> steps become numbered instructions
-> allowed-tools scoped (if needed)
-> reference files / scripts bundled (if needed)
-> tested for trigger accuracy
-> packaged SKILL.md folderNotice that packaging - the frontmatter, the folder, the file layout - shows up late in this sequence, not first. Skills that go wrong often go wrong because someone wrote the YAML block before they had actually nailed down the steps.
Not every repeated task should become its own Skill. Some belong as a section inside a broader, related Skill instead of a new package of their own, especially if they share most of their steps with something that already exists.
A useful test: if two tasks would trigger on nearly the same description, they probably belong in one Skill with a branch in the instructions, not two Skills competing for the same trigger.
As a team's Skill library grows, the idea-to-package path also has to account for discoverability among many Skills, not just correctness of one. A description that would have been fine in isolation can become ambiguous once five other Skills sit next to it with similar wording.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| One Skill per narrow task | Descriptions stay precise and easy to trigger correctly | Can sprawl into many small, overlapping Skills | Small teams, a handful of well-separated tasks |
| One Skill with branching steps for related tasks | Fewer packages to maintain and discover | Instructions get longer and need clear internal branching | Related tasks that share most of their steps |
| Bundled reference files split out early | Keeps the main SKILL.md body short and scannable | Adds files to track and keep in sync | Tasks with genuinely large reference material (style guides, schemas, templates) |
The packaging stage also has a natural moment for review: once you have a full SKILL.md, read the description and the first three steps as if you were Claude seeing them for the first time, with no memory of writing them. If the "when to use" isn't obvious from the description alone, that is the stage to revisit, not the last one to fix.
description field carries almost all of the discoverability weight, not the name. A precise name with a vague description still won't trigger reliably.SKILL.md file with a name and description in its frontmatter, plus a body of instructions. Bundled files and allowed-tools are optional additions.Claude matches new tasks against a Skill's description to decide whether to load it at all. If the description doesn't trigger, the instructions never get read, no matter how good they are.
You risk producing a technically valid package with vague or generic instructions, since the folder and frontmatter don't force you to think through the actual steps.
No. Many Skills are a single SKILL.md file with no bundled resources at all. Add extra files only when the instructions genuinely need to point to something too large to inline.
It means running a task you'd expect to activate the Skill and one you wouldn't, then confirming Claude makes the right call in both directions - not just checking that the Skill produces a good result once it's already been invoked.
The description is too vague or too broad, so Claude either doesn't recognize the matching task or matches on the wrong one. This is almost always a description problem, not an instructions problem.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.
Reviewed by Chris St. John·Last updated Jul 16, 2026