Every week you tell Claude the same thing. How your quotes are formatted. Which fields your invoices need. The order you onboard a client in. You explain it, Claude does it, the conversation ends, and the knowledge dies with it. Next week you type the whole thing again.
A skill fixes that. It is a folder that holds your instructions, and Claude reads it when the job comes up. Teach the workflow once. Claude runs it every time after.
Here is the whole build. The folder, the one field that decides whether Claude ever loads it, the instructions, and the tests that prove it fires when it should. You can ship your first working skill in about thirty minutes.
What a skill actually is
A skill is a folder with one required file inside it.
That file is SKILL.md. It holds your instructions in plain Markdown, with a short block of settings at the top. Everything else in the folder is optional: a scripts/ folder for code Claude can run, a references/ folder for longer docs it reads only when needed, an assets/ folder for templates or fonts it uses in output.
The clever part is how Claude reads it. Skills load in three stages, and this is the whole reason they do not slow Claude down.
Stage one is the settings block at the top of the file. Claude always sees this. It is a name and a one-line description of what the skill does and when to use it. Nothing more.
Stage two is the body of SKILL.md. Claude only reads this when it decides the current job matches the description. This is where your real instructions live.
Stage three is the linked files. Claude opens those only if a step tells it to. A two-hundred-line API reference sits in references/ and costs you nothing until the moment it is actually needed.
So the settings block is a cheap always-on advert. The body is the manual. The linked files are the appendix. Claude pulls each level only when the work calls for it.
Step one: name two or three jobs
Do not open a file yet. First write down two or three concrete things you want the skill to handle.
Concrete means you can name the trigger and the result. "Help with projects" is not a job. "When I say plan this sprint, pull the current status, suggest priorities, and create the tasks" is a job. You can picture the start and the finish.
Ask four questions for each one. What is the person trying to get done. What are the steps. What tools does it need, either Claude's built-in ones or a connected service. What knowledge does Claude need baked in that it would not otherwise have.
Skills tend to fall into three shapes. Knowing which one you are building tells you what to focus on.
| Shape | What it does | Example |
|---|---|---|
| Creation | Produces consistent output: documents, decks, designs, code | A frontend-design skill that builds to your brand |
| Automation | Runs a multi-step process the same way every time | A skill that walks a whole client onboarding |
| Connector layer | Adds workflow smarts on top of a connected service | A skill that turns raw Notion access into your team's real process |
Most skills lean one way. The connector layer only applies if you have already wired Claude to an outside service. If you have never done that, the MCP servers that give Claude hands is where that starts. If you have not, ignore that shape and build one of the first two.
Step two: build the folder
Make a folder named in kebab-case. Lowercase, words joined by hyphens, no spaces.
client-onboarding is right. Client Onboarding, client_onboarding, and ClientOnboarding are all wrong and will be rejected. The folder name and the skill name should match.
Inside it, the only file you must have is SKILL.md. The spelling is exact and case-sensitive. Not skill.md, not SKILL.MD. If Claude cannot find a file spelled precisely SKILL.md, the upload fails with a "could not find SKILL.md" error, and this is the single most common reason a skill will not load.
One more rule that surprises people. Do not put a README.md inside the skill folder. All the instructions go in SKILL.md or the references/ folder. A README belongs in your public repo for human visitors to read, which is a separate thing covered later.
The full shape, once you add the optional parts:
Copy this.
client-onboarding/ ├── SKILL.md # required ├── scripts/ # optional: code Claude can run ├── references/ # optional: docs loaded on demand └── assets/ # optional: templates, fonts
Step three: write the description that decides everything
Open SKILL.md. The top of the file is a small settings block wrapped in three dashes above and below. This is the part that decides whether your skill ever runs.
Two fields are required. name and description. Here is the whole minimum:
Copy this.
--- name: client-onboarding description: Runs the full client onboarding process for our agency. Use when the user says "onboard a new client", "set up a new account", or "start onboarding". ---
That is a complete, working skill header. Everything below the second line of dashes is your Markdown instructions.
The description is the field people get wrong, and it is the one that matters most. Claude reads it to decide, on every message, whether your skill is relevant. Get it vague and the skill never fires. Get it specific and it fires when it should.
A good description does two jobs in one sentence. It says what the skill does, and it says when to use it, using the exact words a person would actually type.
Weak, and it will never trigger:
Copy this.
description: Helps with projects.
Strong, and it triggers on the real request:
Copy this.
description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when the user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".
The pattern to copy: what it does, plus when to use it, plus the trigger phrases in quotes. Keep it under a thousand characters. Name the file types if they matter. And do not put angle brackets in it. The < and > characters are banned in the settings block for a security reason, since that block goes straight into Claude's system prompt and stray tags could inject instructions. Skill names starting with "claude" or "anthropic" are reserved and blocked for the same reason.
Step four: write the instructions
Below the settings block, write what Claude should do. Plain Markdown, numbered steps, headings for each stage.
The rule here is one word: specific. Vague instructions produce vague behavior. Every step should be something Claude can act on without guessing.
Weak:
Copy this.
Validate the data before proceeding.
Strong:
Copy this.
Run `python scripts/validate.py --input {filename}` to check the format.
If it fails, the usual causes are missing required fields or a date not in YYYY-MM-DD form.
Three things separate a skill that works from one that half-works.
Put the critical rules at the top, not buried on line ninety. If a step must never be skipped, say so with a ## Critical heading and list the exact checks. "Before creating the project, confirm the name is non-empty and a start date is set" beats "make sure everything is valid."
Include the errors. When something breaks, Claude should already know what to do. Name the common failure and the fix inside the instructions. "If the connection is refused, check the server is running under Settings, then reconnect" turns a dead end into a recovery.
Give at least one worked example. Show a real request, the actions Claude takes, and the result. Examples teach faster than description.
And keep SKILL.md lean. If it grows past a few thousand words, move the detail into references/ and link to it from the step that needs it. That is the third level of loading doing its job. The main file stays a tight manual; the deep reference sits in a linked file Claude opens only when a step points at it.
One hard-won note from the guide's own authors. For a check that absolutely cannot fail, do not trust the instructions to enforce it. Write a small script that performs the check and have the skill run it. Code is deterministic. Language is not.
Step five: test whether it fires
A skill has two ways to fail. It does not load when it should, or it loads and does the wrong thing. Test both.
First, triggering. Write down five or six ways a real person might phrase the request, then check the skill loads on all of them and stays quiet on unrelated ones.
Copy this.
Should load: - "Help me onboard a new client" - "Set up a new account for Acme" - "Start the onboarding for our new customer" Should stay quiet: - "What's the weather today?" - "Write me some Python"
There is a fast way to debug this. Ask Claude directly: "When would you use the client-onboarding skill?" It will quote your description back at you. If the answer is missing the case you care about, the description is what to fix, not the instructions.
Second, function. Run the skill on a real task and check the output is actually right. The account gets created, the tasks land with the correct fields, the errors get handled instead of crashing the run.
There is a smart way to build up to this. Do not test broadly from the start. Take one hard task and iterate on it in a normal chat until Claude nails it. Then lift that winning approach into the skill. You get faster signal from one difficult case than from twenty shallow ones, and you are baking a proven method into the folder rather than a guess.
If you want the fastest possible start, the skill-creator skill is built into Claude and can generate a first draft from a plain description, then flag weak spots like a vague trigger or a missing test. It writes and reviews. It does not run your test suite for you, so the checks above are still yours to do.
Step six: share it
Once it works, distribution is short.
For yourself, drop the folder in Claude Code's skills directory, or in Claude.ai upload it as a zip under Settings, then Capabilities, then Skills. For a team, an admin can push a skill across the whole workspace so everyone gets it and it updates centrally.
For the public, host it on GitHub. Public repo, a clear README written for the humans browsing it, install steps, a screenshot or two of it working. That README lives at the top of the repo, not inside the skill folder, since the folder still must not contain one.
Here is the part that matters beyond Claude. In December 2025, Anthropic published the skill format as an open standard, the same move it made with MCP. Within months, other agents were reading the exact same SKILL.md files: Codex CLI, Cursor, Gemini CLI, and more. So the folder you write is not locked to one vendor. Build it once, and it works whether the person on the other end runs Claude or Codex. That portability is the point. You are writing a workflow, not betting on a model.
The four failures and how to fix them
Almost every broken skill is one of four problems.
It will not upload. The error names a missing SKILL.md. The file is misspelled or miscased. Rename it to exactly SKILL.md and confirm with ls -la.
It never triggers. Claude does not load it even on an obvious request. The description is too generic. Add the specific phrases a user would say, especially any technical terms, and re-test with the "when would you use this skill" trick.
It triggers too often. It loads for things it should ignore. Tighten the description and add a negative instruction: "Do NOT use for simple data exploration, use the data-viz skill for that." Telling Claude when to stay out is as useful as telling it when to step in.
It loads but ignores the instructions. Usually the instructions are too long, or the key rule is buried, or the wording is soft. Cut the length, move the critical steps to the top under a bold header, and replace "make sure to validate properly" with the exact checks to run. If a rule is non-negotiable, put it in a script.
Honest: when not to build a skill
A skill is worth building when the workflow repeats and the steps are stable. Sprint planning every two weeks. Onboarding every new client the same way. Reports in the same shape each month. That is the sweet spot.
It is a bad fit for one-off work. If you will do the task once, just ask Claude to do it. Wrapping a single request in a folder is wasted effort.
There is a real cost to over-enabling. If you turn on dozens of skills at once, responses can get slower and sloppier as the settings blocks pile up in context. If you have more than twenty or thirty active, enable them selectively instead of leaving all of them on.
And a skill inherits the limits of the tools it uses. If it depends on a connected service that is down or unauthenticated, the skill fails there. Test the connection on its own before you blame the skill.
None of this is measured with a lab instrument yet. Success here is partly judgment. Run the same request three times and see if the output holds its shape. Watch how often you have to correct Claude mid-task. Those signals tell you more than any single number.
If you only do one thing this week
Pick one workflow you have typed into Claude more than twice. Not the ambitious multi-service one. The boring, repeated one.
Make a folder. Write ten lines of SKILL.md: a name, a description with the real trigger phrases, and the steps you already type by hand. Upload it and run it on a real task.
If it fires and does the job, you have removed that explanation from your week for good. If it does not, you have spent thirty minutes and learned exactly which line to fix. Either way you now know how to build the next one, and the one after that is your whole operation, one folder at a time.