How to create the perfect Claude skill: principles every AI user needs

Skills are becoming the de facto way humans interact with agents and LLMs, but mostusers are about to build the wrong version of the thing the market has already converged on. In the six months between October 2025 and April 2026, four separate teams shipped the same primitive.

The convergence ran wider than the vendors themselves. The practitioners who build skills at scale started publishing how they actually work, and the architecture they describe rhymes across every source.

Four independent teams, talking to four overlapping audiences, with the same structural parts showing up in every one of them.

The category is starting to set. The interface between a human and an agent, for any work that runs more than once, runs on someone else's behalf (or runs unattended), is no longer the chat window. It is the skill, and the trap is already forming inside this same shift: a saved prompt in a folder is not a skill. A prompt tells Claude what to do once, while a skill tells Claude how to behave every time the situation reappears. The difference looks small inside a document, but it is the entire difference between AI as a chat window and AI as part of the operating system of a business.

The thing is most users ship their first skills, which are just prompts in costume. They will paste a prompt that works into a folder (or use Anthropics 'skill-creator') add some frontmatter, and call it a skill.

The file fires and returns output, which, by every visible signal, it works. The architecture underneath is missing every structural part, which means Claude has nothing to anchor against the next time the situation appears.

This long read is the architectural vocabulary to tell the difference, and the way to actually start building skills well from the next one. Depending on your AI journey to date, you might want to skip ahead:

I broke this down in detail here. Repeating the definition:

Think of a Claude Skill as an ability that Claude can unlock, like giving it a new power or special training. Once Claude has been taught this new ability, it instantly knows the ability exists, what it does, and it will automatically invoke that Skill whenever it’s relevant. This is the game changing part:

Literally speaking, a Claude Skill is a:

The formula: Skill = prompt + tools + assets.

Major benefits:

For example, when turning podcast transcripts into the relevant meta data and information for YouTube, Spotify, The AI Corner Corner newsletter, and a summary post for LinkedIn, this used to require copy-pasting transcripts and outputs from one Claude Project or Custom GPT to the next, with a lot of back and forth to improve the output to my liking. With Claude Skills, I've automated this process from transcript through to uploading the content into the relevant platforms, along with other checks, for uploading into the relevant apps.

As you can see, skills are not just a developer feature, they work for anyone interfacing with the internet and documents on a computer.

**The clearest way to understand a skill is to think about how a workplace operates.**When a new staff member arrives, no one hands them an encyclopedia of every fact the business knows. They get three things instead.

A skill is the agent equivalent. It is not a knowledge dump, it is the artefact that hands Claude the role, the locations, and the judgement. When the situation appears, Claude is told:

The skill is operational, not exhaustive.

To be super clear, the cleanest one-line definition the skill-building doctrine arrived at is a skill works like a method call: it takes parameters, so the same procedure with different parameters produces radically different outputs.

A skill called /investigate can run a thousand different investigations from one file, while a skill called /investigate-client-X is the same procedure hardcoded for one case. The difference between a real skill and a saved prompt is often that a real skill is built to be re-used with new parameters, while a saved prompt is built to be re-used unchanged.

Across every major vendor, the file format is the same. A folder, with a SKILL.md file inside it carrying a small YAML header (structured metadata written at the top of a file commonly used to give AI systems extra instructions and context before the main content starts) at the top and plain instructions in the body. Sometimes supporting resources live alongside it. It's the same name and same shape, on Anthropic, Microsoft, Google, and the OpenAI agent layer.

Three questions sort any artefact onto the right side of the line:

Take a user who drafts client follow-up emails. On average, they have a saved prompt they paste in three times a week. It tells Claude the tone, the structure, what to avoid, and maybe a few lines of context about the deal stage. The output is good, and they have been using it for months. By every visible signal, it works.

That is a prompt. The prompt is useful and reliable, but it is not a skill.

The skill version of the same job is a different artefact. It reads the user's CRM context before drafting, and refuses to draft when the deal stage is missing, telling the user which file to update.

It follows the same section order every time. It scope-fences the parts of the email it will not write, such as the compliance disclosures or the signature block, pointing at the sibling skill or template that owns those.

It exits by confirming the draft path and offering to send it. Every correction the user makes to the output gets appended back to the file, so the next draft does not need the correction.

It's the same job, the same user, on the same Claude account. One file is a prompt the user pastes in three times a week. The other is a method call Claude fires the same way every time the situation appears. Once an user sees the difference between those two artefacts, the rest of this article becomes the work of converting one into the other.

A great skill has two jobs.

In simple terms: a great skill needs to be well placed and well built.

A beautifully written skill can still fail if it sits inside a messy system. A clean system can still fail if the skill asks the AI to do work it is bad at, like counting rows or checking exact numbers.

So we need to look at both sides: the system around the skill, and the structure inside the skill.

What follows is four layers:

Every agent platform has two layers.

Most users put all their rules in the always-on layer because it feels like the most important place. That is the mistake.

Every rule in the always-on layer costs the agent attention on everything it does, even when the rule has nothing to do with the task. The rules pile up, the agent's attention gets divided, and the output gets worse (example below visualising how bloating the context window where an agent works results in context rot = output degradation).

Source: https://www.trychroma.com/research/context-rot

Garry Tan, who runs his own Claude library, hit this wall in public. His always-on file grew to twenty thousand lines. The agent got worse at every task. He cut it down to two hundred lines of pointers. Each pointer says "if this situation appears, load this skill", and the agent's output improved across every task at the same time.

The move is the same on every platform. Keep the always-on rules layer small, push the actual work down into the skills, which only load when the situation appears. The skill carries the knowledge, whereas the always-on layer just points at the right skill at the right time.

The harder truth is that this is the most expensive mistake a user can make in a skill, and it is the hardest to spot from the outside.

The agent is brilliant at specific kinds of work: jobs like reading, interpreting, synthesising, writing in a particular voice, spotting patterns in a long conversation, and choosing between three plausible options when context matters. Give the agent this kind of work and it is extraordinary.

The agent is largely terrible at a different kind of work: counting the rows in a list, comparing two numbers, working out which of two dates came first, checking that a code is in the right shape, or doing maths. Give the agent this work and it will hand back a plausible-looking answer that is wrong, where the number is off by one or the date is off by a week. The models are certainly improving in accuracy for this kind of deterministic work.

The technical names for these two kinds of work are "latent" and "deterministic". An every day user does not need the jargon. The shorthand is thinking work (latent) and counting work (deterministic).

Increasingly teams are realising not everything requires and agent, and hybrid approaches of using thinking and counting techniques are a great combination.

Challenge is the output often looks right, and nobody notices until something downstream breaks, and by then the damage is done.

A real skill names every step as one or the other and routes each one to the right place. The agent does the thinking, whereas a script does the counting. The script hands the answer back to the skill, and the agent thinks about what to do next. The agent never makes up a number or a date itself.

A user working entirely inside a web app like Claude.ai or ChatGPT and has never touched a script, but the principle still applies. Modern agent platforms have a built-in calculator, a built-in date function, or a sandboxed code cell where the agent can run a few lines of code on demand. The script does not need to be impressive, it just needs to exist, so the skill never asks the agent to do the kind of work the agent it doesn't specialise in.

The challenge is that every skill library has the same problem. The user builds a skill. Next time the situation appears, the agent has to decide whether this skill is the right one, which it does by reading the skill's description.

A description that says "helps with newsletters" is invisible. There is nothing for the agent to match against. Garry Tan audited his own library and found 15% of his skills were in this state. Those skills existed and worked, but nothing ever pointed the agent at them.

The fix is to write descriptions that do three jobs in three sentences.

That third sentence is the one most users skip. It is also the one that costs them most when two related skills in their library could plausibly fire on the same trigger. Without it, the agent picks roughly at random. The user gets the wrong output and blames the agent.

A real example: a description doing all three jobs

This is the actual customize skill in Anthropic's commercial-legal plugin on GitHub (Anthropic's repo uses the US spelling). The description at the top is what the agent reads to decide whether to fire this skill or a different one.

Three sentences = three jobs.

The three realities above describe the system the skill sits inside. The six parts below describe what has to be inside the file itself. Each part has its own visible failure mode and a real example lifted from a working skill in Anthropic's claude-for-legal plugin.

The first numbered step of a real skill reads the files the skill depends on. That might be the team's playbook, the user's profile, the output of the previous skill in the chain, or the setup file the user filled in at install time.

If any of those is missing or still contains placeholder text, the skill stops. It refuses to run on guesses, and it tells the user exactly what to run to fix the situation.

Without this step, a skill does not throw an error when something is missing. It just runs, and the output looks fine on the surface. The user has no signal that the skill never read their actual context. Six months later they realise every output has been generic, ignoring every customisation they ever entered.

A real example: a skill stopping cleanly.

Here is the first numbered step inside the same customize skill, from the same GitHub file. The step starts by reading the config. The second half is what happens when the config is not ready.

The stop is what makes the skill safe, whereas the redirect is what makes it useful. A skill that will not stop is a skill that will lie.

Reality 3 already covered why this is the most important piece of writing in the file. This is the file-level addition. The description lives in the YAML frontmatter at the very top of the SKILL.md, in a field called description. It is the first thing the agent reads when scanning the library for a skill to fire.

Two things make the description block work as a piece of file structure.

The mistake operators make at the file level is hiding the routing logic somewhere else, like in a*## When this runs* section halfway down. The agent never gets that far during routing. The description has to do the work itself.

Every real skill follows the same top-to-bottom order. A heading at the top, then a numbered workflow, then examples, then output rules, then guardrails, then a section called "What this skill does NOT do", and finally a closing action.

Same order every time, in every skill the user builds.

The reason this matters is that the agent reads the file top to bottom every time the skill fires, and what shows up first gets the most weight. Workflow before philosophy, constraints high in the file, examples after the rules so the agent has something to pattern-match against.

Aakash Gupta, a product leader who has tested seventy-five skills in public, has a cautionary tale here. His fitness-coach skill had the rule "never recommend lifts that risk injury" buried at line seven hundred of a single file. The agent skipped it and the output recommended risky lifts. Anything below roughly line three hundred gets weaker as the agent's working memory fills up, which means critical rules have to live high in the file.

A real example: the section order, rendered.

Here is the workflow section of Anthropic's build-guide skill on GitHub. Step 1, then Step 2, then Step 3. Same order every time the skill fires. Same order in every skill in the same plugin.

The agent learns the layout once and finds the right section in every skill it touches.

The part most teams skip is the scope fence, which is the section that protects the skill from turning into a worse version of three other skills.

The idea is pretty simple in that the user writes a section listing three to five things this skill deliberately refuses to do. For each refusal, the section points at a different skill that handles that work.

A quick word on the jargon.

Without this section, a skill becomes the dumping ground for every adjacent request. The user asks the agent to run the weekly status skill, and the agent starts drafting a monthly review at the same time because nothing told it to stop. The output gets worse as the skill absorbs more jobs (production data confirms this). A ten-step skill running at 95% reliability per step only succeeds 60% of the time across all ten steps. The bigger the skill, the worse it gets, therefore, single-responsibility skills win.

A real example: a skill drawing its own boundaries.

This is the "What this skill does NOT do" section from Anthropic's build-guide skill, from the same GitHub file.

There are four refusals, each one points to where the excluded work actually lives. The skill defines itself by what it refuses to absorb.

A real skill ends with four things:

This is what turns a tool into a workflow. Without an exit block, the skill prints output and stops, where the user has no signal whether the work is actually finished. The classic case is the investor update that ships with '[MRR figure]' still in the prose, where the agent wrote everything else, nobody noticed the placeholder, and the board sees it.

A real example: a skill closing the loop.

This is the exit block from Anthropic's build-guide skill, from the same GitHub file. The placeholders in square brackets get filled in at runtime.

The user then knows the work is done and knows where to find the file.

Every real skill carries three to five named failure modes, where each one is a verb-led instruction followed by one sentence on what breaks when the failure happens.

The strongest guardrails name the actual person who loses when the rule fails, whether that is the lawyer who relies on a clause, the user who signs off on a draft, or the team that inherits an undated commitment. Naming the loser is what improves the rule. A rule with a named loser gets followed, whereas a rule that just says "don't do X" gets rationalised away the first time the agent meets a situation that does not quite fit.

The better move is matching the strictness of each guardrail to how fragile that step is.

A skill that is uniformly loose hallucinates on the fragile steps. A skill that is uniformly tight produces robotic output on the creative ones. The best approach is calibrating the strictness step by step, matching the level of control to the level of risk.

The key piece most users miss is that a great skill is not finished when it works once. A great skill compounds over and over.

The pattern is fairly straightforward = the skill runs and the user edits the output. The difference between what the agent produced and what the user actually wanted gets pulled out and added back to the skill, usually to a learnings file the skill reads at the start of every run.

A skill that never updates is a static prompt that gets older, while a skill that updates with every correction loaded in context it reviews every time is infrastructure that gets better on every occasion.

The test for whether a skill has crossed into compounding, from Garry Tan: "If the user asks for the same thing twice, the skill failed".

The second ask is the signal that the first run produced output, but did not produce a skill. The fix is not to ask better, but to take the correction and fold it back into the skill so the next run does not need it at all.

**This is the difference between "I built a skill" and "I am building operational AI".**An operational library is the cumulative output of every correction the user ever made. A static library is a folder full of YAML headers that produce roughly the same output every quarter.

The moment an user has ten skills in the library, a new question lands. What makes a great skill-creator?

Anthropic's skill-creator is the file that builds the other skills. It's the factory floor of most people's AI instance.

Anthropic ships one, and it is good. It is the equivalent of a beautifully-made knife sharpener that knows nothing about which knives are in the user's drawer.

What the baseline does not do is treat the new skill as part of a larger system.

The strongest meta-skill does both, in this order.

The baseline is the first kilometre of the work. The two directions are the road.

The bottleneck is never the agent's intelligence, because the agent already knows how to reason, synthesise, and write. It fails because it does not understand the user's data/context, the user's conventions, or the particular shape of the user's problem. Skills are how the user teaches the agent.

The way to teach it well comes down to a short list.

Not the whole library, or the new skill the user wishes existed. Pick the one that runs the most often.

Read down the file and ask, for each of the six parts:

The user finishes with a real diagnosis of one real skill, not a theory of skills in general.

Not all six, just the lowest-scoring single part.

Make an update to the skill to see a real difference in the output. The point is not to make the skill perfect. The point is to feel the difference one part makes, in one skill, in one work week.

The next time the user corrects the output of any skill, the rewrite or the edit or the "no, do it like this", append the rule to the skill the moment the correction lands.

The skill is now operational infrastructure, not a prompt with a YAML header. Repeat for the next correction. Then the one after that. By the end of a quarter the user has a library that learns instead of a library that ages.

Most users have not realised the skill-creator is itself a skill. A weak skill-creator silently produces weak children.