Skill Writing 101
The mechanics of writing a skill are easy to learn. This is the lesson on how Claude decides what to read and when — the part that decides whether what you build performs like an expert's.
You Don't Need to Code. You Need to Understand How Claude Reads.
If you set out to build with AI by hunting for the right words — the exact phrasing that will make Claude do what you want — you will land on a workable prompt. You will not land on a skill that behaves like it was built by someone who understands the system underneath it.
A skill is not a longer prompt. It is a structure Claude reads in a specific order, for specific reasons. Once you can see that order, you stop guessing at wording and start building something with real architecture behind it — even if this is the first skill you have ever attempted.
The gap you are standing in is not between knowing AI exists and not knowing it exists. It sits between being curious about what AI can do and understanding how the specific system in front of you was built to think. Close that second gap, and the skill you write behaves like it — regardless of how much experience you brought in with you.
The Three-Layer Skeleton
Claude does not load an entire skill into its working memory the moment your account has it installed. It reads a skill in layers — the same way you would draft a skeleton prompt before dressing it out into something more advanced. Understanding those layers is the whole lesson.
The skill's name and a short description. This is the only part visible by default, for every skill installed, all the time — it is what Claude scans to decide whether a skill is even relevant to the request in front of it.
The full body of the skill's guidance. This loads only once Claude has matched the request to that nameplate. Before that moment, it is not sitting in working memory at all.
Bundled scripts, templates, and reference files. These load only if the task in front of Claude calls for them — a specific example, a template, a longer reference doc. Most tasks never touch this layer.
Working Memory Is Not Free, and This Isn't Only About Cost
There is a plain economic reason for the three-layer structure. Claude's working context is a limited resource, so keeping the always-on layer down to a name and a description means the cost of having a dozen skills installed stays close to nothing, right up until one of them gets used.
But cost is only half of it. Even in a world where context carried no price tag, loading every reference document into every task would bury the instructions that matter under everything that doesn't. A skill that hands Claude fifteen pages when the task needed three sentences produces weaker output — not only slower output.
A well-built skill protects Claude's attention with the same care it protects its token budget. Keeping the signal clean is not a side effect of good architecture. It is half the reason the architecture exists.
The Benefit Is Earned. It Doesn't Come Standard.
Most first-time skill builders give away this advantage without realizing it. A skill only benefits from the three-layer structure if its content is split that way: a lean nameplate, a scoped set of instructions, and reference material offloaded into its own files.
Write everything — the full method, every example, every reference table — straight into the instructions layer, and what you have is still, technically, a skill. It will trigger. It will run. It will carry the full weight of every page on every single use, because nothing was left behind to defer.
The mechanism is not a rule Claude enforces on you. It is a discipline you bring to the build yourself: keep the instructions body tight — roughly the length of a focused briefing, not a manual — and move anything long, situational, or reference-only into its own file so it only gets pulled in when it earns its place.
What Separates a Reliable Skill From a Brittle One
A skill written only for the tidy version of a task falls apart the first time reality doesn't cooperate. The version of your business a well-built skill has to handle is the week that doesn't look like every other week.
A boundary situation — the kind a skill built by someone who knows what they're doing accounts for — won't show up in your first few tests, but it is realistic enough that it eventually will. Think of the client with nothing to invoice this month, or the week the inbox has zero questions in it. Ordinary — not the case you happened to test.
- →Test the empty case first. If your skill assumes there is always at least one item to process, ask what it does when there is none — that is usually the first boundary situation to break a build.
- →Test the incomplete case second. Real inputs arrive half-finished more often than finished. A skill that only performs with a complete brief is a skill that fails on an ordinary Tuesday.
- →Test the "nothing to report" case third. A task with no findings, no update, or no action needed is still a valid outcome — a skill that can't say "nothing here" convincingly will invent something instead.
You Are Not Starting From an Empty Toolbox
Before you write a single line, it helps to know what already exists versus what you are responsible for creating. Anthropic ships a set of ready-made skills the moment the feature is switched on for an account — including one that walks you through building a new skill interactively, asking what you need and assembling the layered structure on your behalf.
What you build — the skills trained on your specific way of working — do not arrive pre-loaded. They exist only once you, or a builder working under your direction, create and add them.
Available the moment the feature is turned on. It interviews you, assembles the layers, and formats the file — no raw folders to touch by hand.
This exists only once you, or someone building on your behalf, create it. This is where the architecture in this lesson gets applied.
Where to Turn It On
None of this matters if the feature sits dormant in your account. The path to enabling it is short, but easy to miss if nobody points you to it directly.
- Go to Settings, then Capabilities, and switch on Code Execution and File Creation.
- The Skills menu will not appear until this is on.
- Go to Customize, then Skills.
- This is where every built-in skill can be toggled individually, and where your own get added.
- Whatever you enable here carries across desktop sessions and scheduled tasks tied to your account.
- It is a one-time setup, not a per-conversation one.
Direct the Builder Instead of Describing the Task
Understanding that a skill lives in three layers changes how you brief the builder. You stop asking Claude's skill-builder for "a skill that does X" and start asking for something with the architecture already specified.
That is the real difference between someone who has a tool available and someone who knows how to direct it. The same builder produces a materially different result depending on what you tell it to protect and what you tell it to defer.
Tell it exactly which requests should trigger this skill, in plain language. Vague wording here means the skill misfires, or never fires at all.
Name what belongs in the always-loaded body versus what is long enough, or situational enough, to live in its own reference file instead.
Give the builder the empty case, the incomplete case, and the "nothing to report" case before it writes a single instruction — don't wait to discover them once the skill is already failing quietly.
The Four-Point Check
- →The description alone tells you when it should fire. If you cannot predict from the name and description whether a given request should trigger it, neither can Claude.
- →The instructions body stays lean. If it reads like a manual instead of a briefing, something in it belongs in a reference file instead.
- →The reference material earns its place. You should be able to name the exact situation that requires each bundled file — if you can't, it probably doesn't belong there.
- →It survives the boundary case, not only the demo case. Run it against the empty case and the incomplete case before you call it finished.
You Already Have the Gold. This Is the Delivery System.
None of this architecture is the valuable part. What you already know how to do — the process you've refined for the people you serve by repeating it more times than you can count — that is the asset.
A skill only gives Claude a way to carry a piece of that judgment forward on your behalf, reliably, at the moment it is needed. Learn the architecture so the vehicle is built well. The gold was never the part that needed building.
Your uniqueness is not a liability. It is the asset. The skill decides when Claude gets to use it.