How to Build a Custom Claude Skill (Step by Step)

Say you paste the same instructions into Claude every Monday. "Format this export the way our board deck expects, right-align the totals, tab per region." It works, you close the tab, and next week you type it all again. A custom Claude Skill is how you write that down once and hand it to Claude for good.

Building one is not the hard part. A working skill can be a single Markdown file in a folder. The hard part is writing it so Claude reaches for it at the right moment, and knowing where a skill stops being useful and a real workflow has to take over. Most custom skills that get built never fire, and the reasons trace back to a few small choices you make before you type a single instruction.

If you have not met the format yet, our explainer on what Claude Skills are covers the mechanics and how they differ from MCP. Here we build one.

What you are actually building

A Claude Skill is a folder. At its root sits one required file, SKILL.md, which holds two things: a short block of YAML metadata at the top, and Markdown instructions below it. That is the entire minimum. Everything else is optional.

Alongside SKILL.md you can add three folders, and Claude opens them only when a task needs them, per Anthropic's Agent Skills overview:

scripts/ for code Claude runs when a deterministic step beats free-form generation, like writing real Excel formulas or filling a PDF form.
references/ for longer documentation Claude loads only when a specific detail is required.
assets/ for templates, fonts, or a brand style sheet the output needs.

That is the whole anatomy. A skill is a table of contents plus the materials it points to. Keep that picture in your head, because the rest of this guide is just filling it in.

Step 1: Pick a job worth packaging

Before you touch a file, name the job. The best skill target is a task you repeat and re-explain to Claude often, that has a right answer you can describe. "Score this inbound lead the way we score them." "Turn a supplier PDF into a row with these exact fields." "Draft a refund reply in our tone."

Scope it to one job. A skill that tries to do invoicing and lead scoring and deck formatting will trigger at the wrong times and confuse Claude about when it applies. Anthropic's own examples each do a single thing, which is why they compose cleanly. Claude can stack a PDF-extraction skill with a spreadsheet skill in one run when each stays in its lane.

If the task happens once a quarter, stop here and just do it by hand. A skill earns its keep on something you hit weekly or more. We laid out that call in full in when to automate a task and when not to. Assuming the job clears the bar, keep going.

Step 2: Create the folder and SKILL.md

Make a folder and give it the skill's name, lowercase with hyphens. Inside it, create SKILL.md. That file opens with YAML frontmatter fenced by --- lines, then the instructions.

The minimum frontmatter is two fields, name and description, confirmed in Anthropic's best-practices guide:

---
name: invoice-formatter
description: Formats raw Stripe or QuickBooks CSV exports into the company's standard monthly invoice layout.
---

# Invoice formatter

When the user gives you a transaction export, produce one invoice per customer using the layout in references/template.md.

A few hard constraints on name, from the platform docs: 64 characters maximum, lowercase letters, numbers, and hyphens only, and it cannot contain the reserved words "claude" or "anthropic". Match the folder name to the name value to keep things sane. Get this scaffold right and the skill exists. Whether Claude ever uses it comes down to the next step.

Step 3: Write the description so Claude actually triggers it

This is the field people get wrong, and a wrong description is why a skill sits installed and never fires. The description is not a label. It is the trigger. It is the one piece of the skill Claude reads up front to decide whether the task in front of it is a match, before loading anything else.

Write it to answer two questions in plain language:

What does the skill do?
When should Claude use it?

Include the concrete triggers: the file types, the task words, the situation. Write it in third person, describing the skill, not addressing the user. Anthropic's own skill-creator skill enforces exactly this shape.

Compare these two. The first never fires. The second does the work.

Weak: description: Helps with invoices.
Strong: description: Formats raw Stripe or QuickBooks exports into the company's standard monthly invoice layout. Use when the user provides a CSV or spreadsheet of transactions and asks for invoices, billing summaries, or a month-end statement.

The hard limit is 1,024 characters for description, per the platform docs. You rarely need that many. Front-load the trigger words, the file types and task phrases, into the opening, because that opening is what Claude scans across every installed skill when it is deciding what is relevant. A vague first line loses to a specific one every time.

Step 4: Write the instructions like a table of contents

The body of SKILL.md, everything below the frontmatter, is where the actual procedure lives. The instinct is to dump every rule, edge case, and example into it. Resist that.

The reason is a loading model Anthropic calls progressive disclosure, described in its launch engineering post. It runs in three stages:

Claude reads only the name and description to judge relevance.
If it matches, Claude loads the full SKILL.md body.
Only if the instructions point to a file in references/, scripts/, or assets/ does Claude open that file.

So a skill can carry 40 pages of reference material and cost almost nothing until the moment Claude needs page 12. That only works if you keep SKILL.md itself lean and let it point outward. Anthropic's best practices put a soft ceiling around 500 lines on the body and tell you to treat it like a table of contents: the high-level procedure inline, the deep detail in references/, the deterministic steps in scripts/.

Practically, that means a body like this. Number the steps. State the rule. When a step has a long lookup table or a fussy format spec, write "see references/regions.md" instead of pasting the table. When a step needs to be exact every time, like a currency calculation, write a small script in scripts/ and tell Claude to run it rather than compute it in prose. Code that runs is more reliable than a model doing arithmetic by hand.

Step 5: Package and install it

Now put it where Claude can use it. The upload has one step everyone trips on.

Zip the folder itself, not the files inside it. The archive's single top-level entry must be the skill folder, with SKILL.md one level down. If you select the contents and zip those, the loose files land at the root and Claude will not recognize the skill. This is the most common install failure, called out in Anthropic's support guide.

Then, in claude.ai, open Settings, go to Customize (or Capabilities), find Skills, click Create skill, choose Upload a skill, and drop in the zip. Toggle it on. Because most skills lean on running scripts, you also need code execution enabled, or the script-backed parts will not do anything. Test it with a prompt that should match, then check Claude's thinking to confirm the skill loaded.

Two shortcuts worth knowing:

In Claude Code, skills are supported in beta and you can invoke one directly by typing /skill-name, per the Claude Code skills docs. We go deeper on that setup in our guide to Claude Code skills. This is the fastest place to iterate.
Anthropic ships a meta-skill called skill-creator that interviews you about the workflow, drafts the folder and SKILL.md, and packages it for upload. If you would rather answer questions than write YAML, start there. It lives in the official skills repo.

Common mistakes that keep a skill from firing

Most first skills fail for a short list of reasons, and none of them are exotic.

The description is too vague to trigger. "Helps with reports" matches nothing specifically. Name the file types and task words. This is the single biggest cause of a dead skill.
You zipped the contents, not the folder. Covered above, and worth repeating because it is silent. The upload succeeds and the skill still never appears to work.
The skill does too much. One folder trying to cover three unrelated jobs triggers unpredictably. Split it into three scoped skills that each do one thing.
Everything is crammed into SKILL.md. A 900-line body defeats progressive disclosure and burns context. Move detail into references/ and point to it.
A "should be exact" step is left to prose. Anything with a right answer, a calculation, a strict format, belongs in a scripts/ file Claude runs, not instructions it interprets.

When to build it yourself, and when to bring in bottta

Here is the honest boundary. Everything above produces a skill that waits for a person to open Claude and ask. For a personal, repeatable task, that is exactly right, and you should build it yourself. It is an afternoon of work and there is nothing to hire out.

The moment the skill needs to run as a business process, the shape of the problem changes. A skill that formats an invoice is one piece. The process is the rest: pulling the closed deal out of your CRM, connecting Claude to Stripe and Slack with live access, running it on a trigger instead of someone remembering, and monitoring it so a silent failure at 2 a.m. does not surface as an angry client email a week later. The skill is the easy 20%. The workflow around it is the 80% that decides whether it holds up at 5,000 records instead of 50.

That build is what we do at bottta. Our AI Automation work turns a good skill into a workflow that runs on its own, with the Integrations wired to your real tools and the monitoring that keeps it honest. Concretely: your custom skill reads the supplier invoice, an integration writes the extracted rows to your sheet, and a trigger runs the whole thing on every new email instead of when someone remembers. We take it on two ways. A $3K per month retainer covers flexible hours, up to 3 active workflows at a time, and ongoing monitoring and fixes. A $4K fixed-scope project ships one defined workflow with integrations included and 30-day post-launch support. Both are on the pricing section. No free tier, because this is built work, not a button.

You can also stitch that wrapper together yourself in a tool like Zapier or n8n and call the API from there. That holds for a simple two-step job. It tends to break the moment the logic gets real, and then you own a brittle chain nobody documented. If you want a sense of when that trade-off tips, our piece on build versus buy versus hire walks the numbers, and Claude for small business covers where the model fits day to day. Build the skill yourself this afternoon. The day it has to become a process that runs without you, bring the build to bottta.

Frequently asked questions

Do I need to code to build a Claude Skill? No for a simple one. SKILL.md is plain Markdown, so a skill that just gives Claude instructions is writing, not coding. You need real engineering once the skill bundles scripts that run, and again when you wrap the skill into an automated workflow with live data and monitoring.

Where do I put the "when to use this" information? In the frontmatter description, not the body. The description is the only part Claude reads to decide whether the skill is relevant, so the triggers, file types, and task words have to live there. The body is for the procedure Claude follows after it has already decided to use the skill.

Why does my skill never trigger? Almost always the description is too vague, or you zipped the files instead of the folder. Rewrite the description to name the exact situation and file types, in third person, and re-zip so the skill folder is the single top-level entry in the archive.

Can I share a skill with my team? Yes. A skill is just a folder, so the zip you upload is the same artifact you send a teammate or check into a repo. Each person uploads it under Settings and toggles it on, or in Claude Code it can live in the project. For a ranked look at which skills are worth installing in the first place, see the best Claude Skills for a lean team and where to browse them in the Claude skills marketplace.

How big can a skill be? The description caps at 1,024 characters and the name at 64. The SKILL.md body has a soft limit around 500 lines, but the whole point of progressive disclosure is that you keep the body short and push the bulk into references/, scripts/, and assets/ that Claude loads only when it needs them.