Skip to main content
Guide10 min read·Updated July 26, 2026
🧩

How to Build a Claude Agent Skill From Scratch (2026)

B

A. Frans

Published July 26, 2026

Agent SkillsClaude CodeTutorialSKILL.mdDevelopers

Most people install skills long before they write one. Fair enough, since installing takes two minutes. But the moment Claude keeps fumbling the same task the same way, a skill you wrote yourself beats any prompt you re-paste for the tenth time. A skill is a folder of instructions Claude loads only when the task calls for it. Here's how to build one from nothing, the manual way, so you understand every piece before you ever reach for a generator.

What a skill actually is

Strip away the branding and a Claude agent skill is a folder holding one required file: SKILL.md. That file has two parts. At the top sits YAML frontmatter with a name and a description. Below it is plain markdown, the instructions Claude follows once the skill loads.

The description carries more weight than anything else in the file. Claude reads it, and only it, to decide whether the skill applies to the task in front of it. The body stays out of context until that decision turns to yes. A fuzzy description means your skill never fires, however sharp the instructions underneath.

Skills can carry more than SKILL.md. Add reference documents, checklists, or scripts the agent runs directly, and Claude pulls them in only when a step needs them. That layering, a short entry file with deeper files linked from it, is what keeps skills fast instead of bloating every prompt.

Step 1: Decide what it does, narrow beats broad

The biggest mistake here happens before you type a word. People try to build a "writing assistant" or a "code helper," and the skill turns to mush because Claude can't tell when to load it.

Pick one repeatable job with a clear trigger. "Rename my downloaded invoice PDFs to a date-vendor-amount format." "Turn a raw meeting transcript into our standup format." "Check a React component against our accessibility checklist." Each has a moment where it obviously fires and a moment where it obviously doesn't. That edge is what makes a skill reliable.

Write the job down in one sentence. If you need "and" twice, you probably have two skills. Split them.

Step 2: Scaffold the folder and SKILL.md

Make a folder named after the skill in kebab-case, and drop an empty SKILL.md inside. That single file is the minimum a skill needs to run:

pdf-invoice-namer/
  SKILL.md
  references/
    naming-rules.md
  scripts/
    rename.py

The references/ and scripts/ folders are optional. Start with just SKILL.md and add the rest once you know you need them. Where the folder lives depends on your setup: a personal skill sits in your Claude skills directory, a project skill ships inside the repo so your whole team gets it. Either way, the folder is the unit.

Step 3: Write the frontmatter, name plus a trigger-rich description

Open SKILL.md and start with the YAML block. Two keys matter:

---
name: pdf-invoice-namer
description: Rename downloaded invoice and receipt PDFs to a YYYY-MM-DD_vendor_amount.pdf pattern. Use when the user drops invoice or receipt PDFs, asks to rename or tidy invoices, or mentions messy invoice filenames.
---

The name is an identifier, keep it short and kebab-cased. The description is where you win or lose. Claude matches the task against this text, so stuff it with the real words a user says when they want this: the file types, the verbs, the synonyms. "invoice," "receipt," "rename," "tidy," "messy filenames." Say what the skill does and when to use it, in the same breath.

A weak description reads "Helps with invoices." A strong one names the trigger conditions so precisely that Claude loads the skill at the right moment and leaves it alone the rest of the time. Spend more time here than anywhere else.

Step 4: Write the body as a procedure, not an essay

Below the frontmatter, write for a reader who acts on every line. Skip the prose warm-up. Give Claude a decision procedure it can follow top to bottom.

Use imperative sentences. "Read the PDF's first page. Extract the vendor name and the invoice date. If the date is missing, check the PDF metadata." Number the steps when order matters. Spell out the edge cases you already know trip things up, because Claude handles what you name and improvises on what you leave blank.

Show the output you want. If the skill produces a filename, paste one correct example. If it fills a template, show the filled template. Concrete beats abstract every time, and a single worked example teaches more than a paragraph of description.

Keep this section tight. A body that runs past a couple hundred lines usually means the skill is doing too much, or that half of it belongs in a reference file.

Step 5: Add reference files and progressive disclosure

Here's the part that separates a fast skill from a slow one. SKILL.md loads into context every time the skill fires. Anything long, a full style guide, a 200-row lookup table, a detailed API spec, should live in a separate file that Claude opens only when a step points to it.

So instead of pasting your entire naming convention into SKILL.md, write one line: "For the full vendor-abbreviation table, read references/naming-rules.md." Claude reads it when it reaches that step and ignores it otherwise. Same idea for scripts. If a step is deterministic, like renaming files on disk, ship a small script the agent runs instead of asking the model to reason through it. Point to scripts/rename.py from the body and let code do the mechanical work.

This is the layering that makes skills scale. The entry file stays short and cheap to load. The heavy material sits one hop away, pulled in only when the task actually reaches it.

Step 6: Test it by triggering it, then iterate on the description

A skill that never loads is worthless, so test the trigger first. Start a fresh session and phrase a request the way a real user would, not the way you wrote the description. Drop an invoice PDF and say "can you clean up these filenames?" Watch whether the skill loads.

If it doesn't fire, the description is too narrow or missing the words people actually use. Widen it, add the synonym you just typed, and try again. If it fires on the wrong tasks, tighten it. This loop, adjust the description, re-trigger, repeat, is most of the work in a good skill. The body tends to settle quickly. The description keeps earning edits.

Once it loads, check the output against your Step 4 example. Feed it a messy real case, not the clean one you designed around. Skills break on the inputs you didn't picture, so go find those inputs now rather than in production.

Step 7: Package, share, and add a security note

When the skill works, you can share it. Zip the folder, publish it to a marketplace, or bundle it as a plugin so a team installs it in one step. The folder structure stays the same wherever it goes.

Add one thing before you ship: a short note telling anyone who installs your skill to read it first. Skills can run scripts, and a script runs with whatever access the agent has. You'd audit a skill before installing someone else's, so make it easy for others to audit yours. Keep the scripts small and readable, comment what they touch, and don't hide logic in a file the reader won't think to open. Trust runs both directions.

The shortcut once you've done it by hand

Anthropic ships a skill-creator skill that scaffolds the folder, writes a first-draft SKILL.md, and prompts you through the frontmatter. It's a real time-saver, but only after you've built one manually. Let it generate the structure and you'll know exactly which parts to fix, because you'll recognize a thin description or a bloated body on sight. There's also sp-writing-skills from the superpowers collection, a guidance skill on how to phrase instructions Claude follows well. Use both as accelerants, not as replacements for understanding the parts.

When you want to see what's already out there before writing your own, browse our directory of Claude agent skills for ones worth studying and installing.

Common mistakes

A vague description. The single most common failure. "Helps with data" gives Claude nothing to match against, so the skill sits unused. Name the file types, the verbs, and the exact phrases a user says.

SKILL.md too long. Everything in the entry file loads every time. Padding it with reference material you could have linked makes the skill slow and expensive. Move the bulk to references/.

No triggers. A description that says what the skill does but never says when to use it. Claude needs both. "Renames invoices. Use when the user drops invoice PDFs or asks to tidy filenames" beats "Renames invoices" every time.

Doing too much in one skill. A skill that formats invoices and drafts emails and audits code will load at the wrong moments and confuse Claude about its own scope. One job per skill. Ship three narrow skills instead of one wide one.

FAQ

Do I need to know how to code to build a skill?

No. A skill with only a SKILL.md file is plain markdown, no code involved. You need code only if you add scripts for deterministic steps, and even then you can start without them and add scripts later once you spot a step that shouldn't rely on the model's reasoning.

How long should the description be?

Long enough to name the trigger conditions, short enough to stay specific. A sentence or two usually does it: what the skill does, plus the file types, verbs, and phrases that should load it. Pack it with the real words users say, then test whether it fires on natural requests.

Where do I put the skill folder?

A personal skill goes in your Claude skills directory so it's available across your own sessions. A project skill ships inside the repository so everyone working on that project gets it automatically. Same folder structure either way, only the location changes.

What's the difference between a skill and an MCP server?

A skill is instructions and files Claude reads to do a task better. An MCP server is a running service that gives Claude new tools and data connections, like reading a database or hitting an API. Skills teach behavior; MCP servers add capabilities. Many setups use both, and the two solve different problems.

Share this article

📬

Get More AI Tool Guides

New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.