How Claude skills are built: the architecture and file structure explained

The three layers of a skill

The Agent Skills specification defines a skill as a directory with a SKILL.md file at the top and three conventional subfolders that may or may not exist. Everything else is optional and the agent will ignore what it does not need.

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

Think of it as three layers. The metadata is the label on the front of a folder in a filing cabinet. The instructions are the procedure inside the folder. The supporting files are the appendices, forms and tools the procedure points to when a step needs them.

• Metadata: the name and description at the top of SKILL.md. This is what the agent reads to decide whether the skill applies to the task in front of it.
• Instructions: the rest of SKILL.md. The steps, checks, priorities and output format the agent follows once the skill is active.
• Resources: scripts the agent can run, reference documents it can read, and assets such as templates it can copy. Loaded only when a step calls for them.

If you have read our guide on SOPs and LLMs, the shape is familiar. A skill is a standard operating procedure written for a model, with the file layout doing the job a well-organised binder does for a new staff member.

SKILL.md: the metadata block and the instructions

SKILL.md has two parts. The first is a block of YAML between two lines of three dashes, called the frontmatter. The second is ordinary Markdown. The frontmatter must be the very first thing in the file. If anything sits above it, the agent treats the whole file, dashes included, as instructions.

---
name: quote-follow-up
description: Drafts a follow-up email for a quote that has had no reply for five business days. Use when the user asks to chase a quote, follow up an estimate, or mentions an unanswered proposal.
---

# Quote follow-up

1. Read the original quote and the enquiry it answered.
2. Check the CRM for any contact since the quote was sent.
3. Draft a short email using the template in assets/follow-up.md.
4. Stage the draft for approval. Never send it.

The specification sets firm rules for the two required fields. The name is at most 64 characters, lowercase letters, numbers and hyphens only, and it must match the folder name. The description is at most 1,024 characters and must say both what the skill does and when to use it. Everything else in the frontmatter, such as a licence, a compatibility note of up to 500 characters, or free-form metadata like a version number, is optional.

The description is the field that matters most. It is the only part of the skill the agent sees before it decides to open the folder, so a vague one means the skill never triggers and an over-broad one means it triggers when it should not. Anthropic's authoring guidance says to write it in the third person and to include the words a user would actually say. Claude Code caps the description at 1,536 characters in its skill listing, so anything longer is cut off.

The Markdown body has no format rules. The recommended contents are step-by-step instructions, examples of inputs and outputs, and the edge cases that catch people out. Anthropic's guidance asks authors to keep the whole file under 500 lines and to push anything longer into separate files. The reason is the loading model described next.

Progressive disclosure: what loads when

An AI agent has a working memory, called the context window, and everything it reads sits in that memory alongside your request and the conversation so far. If every installed skill were read in full at the start of every session, a library of 50 skills would crowd out the actual work. Skills avoid this by loading in three stages, which Anthropic calls progressive disclosure.

• Stage one, at startup: the agent reads only the name and description of every installed skill. The specification budgets about 100 tokens per skill for this.
• Stage two, on activation: when a task matches a description, the agent reads the full SKILL.md body. The specification recommends keeping this under 5,000 tokens, which is why the 500-line limit exists.
• Stage three, on demand: scripts, references and assets are read or run only when a step in the instructions points to them. Until then they cost nothing.

The practical consequence, in Anthropic's own words, is that the amount of material a skill can bundle is effectively unbounded. A skill can carry a complete product catalogue, a full style guide or a folder of legal templates, and the agent pays for only the pages a given task needs.

This is also why the description costs more than it looks. It is loaded on every turn of every session whether or not the skill is used. Ten skills with bloated descriptions are a permanent tax. Ten skills with tight descriptions and rich reference folders are close to free until called on.

Scripts, references and assets: the supporting folders

The three optional folders serve different jobs and the agent treats them differently. Getting the split right is most of what separates a well-built skill from a long prompt saved in a file.

scripts/ is executed, not read

A script is code the agent runs through the shell. Only the script's output enters the agent's memory, not the code itself. Anthropic's guidance prefers scripts for anything deterministic: validating a file, extracting fields from a form, checking that a plan is consistent before it is applied. A pre-written script is more reliable than code the model writes fresh each time, gives the same answer every run, and saves the tokens that generating the code would have cost. Instructions should say clearly whether a file is to be run or read as an example of an approach.

references/ is read when a step needs it

Reference files hold the detail that does not belong in the main instructions: an API reference, the rules for one region, the schema of one dataset. Two rules from the authoring guide keep them useful. Link every reference straight from SKILL.md, one level deep, because the agent may only skim a file that is reached through another file. And give any reference longer than 100 lines a table of contents at the top so the agent can see what is in it from a partial read.

assets/ is copied or filled in

Assets are static resources: document templates, configuration templates, images, lookup tables. The agent does not learn from them so much as use them. A quote template, a brand colour file or a sample invoice belongs here.

Anthropic's own pdf skill, published in its public skills repository, shows the pattern at full size. The instructions file is 314 lines. Two reference files, forms.md and reference.md, sit beside it for form filling and the library API. A scripts folder holds eight Python tools for tasks such as extracting form fields, checking bounding boxes and filling fields, each run on demand rather than read.

pdf/
├── SKILL.md
├── LICENSE.txt
├── forms.md
├── reference.md
└── scripts/
    ├── check_bounding_boxes.py
    ├── check_fillable_fields.py
    ├── convert_pdf_to_images.py
    ├── create_validation_image.py
    ├── extract_form_field_info.py
    ├── extract_form_structure.py
    ├── fill_fillable_fields.py
    └── fill_pdf_form_with_annotations.py

Where skills live and how they get switched on

A skill's location on disk decides who can use it. In Claude Code there are three places you will meet in practice. A personal skill lives in a skills folder in your home directory and works in every project on that machine. A project skill lives in a .claude/skills folder inside one repository and travels with the code, so everyone who clones the repository gets it. A plugin skill is packaged with other skills and installed from a marketplace.

~/.claude/skills/<skill-name>/SKILL.md        # personal: every project on this machine
<repo>/.claude/skills/<skill-name>/SKILL.md    # project: this repository only
<plugin>/skills/<skill-name>/SKILL.md          # plugin: wherever the plugin is enabled

A plugin is a thin wrapper around a folder of skills. Its manifest, a small JSON file, names the plugin, its author and licence, and points at the skills directory. The marketing library we use on this site is built this way: one manifest, one skills folder, 50 skill folders inside it. Installing the plugin installs all of them, and each becomes available under the plugin's name, for example marketing-skills:seo-audit.

Skills switch on in two ways. The agent invokes a skill itself when your request matches its description, which is the normal path. You can also invoke one directly by typing a slash and its name, which is useful for procedures you want to run on purpose rather than have the agent guess at. Two frontmatter switches tune this: one hides a skill from the agent so only a person can run it, the other hides it from the menu so only the agent can.

A real example: the seo-audit marketing skill

Here is the folder for the seo-audit skill from Marketing Skills for AI Agents, the open source library we covered in our beginner's guide. It is a good example because it is entirely text, no scripts, and still uses every layer.

seo-audit/
├── SKILL.md
├── evals/
│   └── evals.json
└── references/
    ├── ai-writing-detection.md
    └── international-seo.md

The description in SKILL.md lists the phrases that should trigger it: SEO audit, technical SEO, why am I not ranking, my traffic dropped, core web vitals, indexing issues, and a dozen more. It also tells the agent what to do with a vague request such as "my SEO is bad" and which sibling skills to hand off to for structured data or programmatic pages. That is the metadata layer doing its job.

The body of SKILL.md is the audit procedure: what to check first, what a plain page fetch cannot see, how to rate each finding and what the report must contain. The two reference files hold specialist material that most audits never need. A site selling only in Australia never loads the international SEO file, and the agent never pays for it.

The evals folder is not part of the specification but it is part of Anthropic's recommended practice. It holds test scenarios with expected behaviour, so the author can check that a change to the instructions still produces a good audit. The authoring guide says to write these before writing extensive instructions, because they show what the model gets wrong without the skill and therefore what the skill actually needs to say.

What this means for a business writing its own skills

The architecture is simple on purpose. A skill is files in a folder, so it can live in your own repository, be read by anyone on your team, be edited without a developer and be moved between agents that support the format. Nothing about it is locked to one vendor's interface.

The same architecture sets the bar for what a good business skill looks like. Anthropic's guidance assumes the model already knows the general subject and asks authors to add only what it cannot know: your tables, your rules, your exceptions, your tone. The example it gives is a data skill that had to be told to always exclude test accounts. For a service business the equivalent is the after-hours rule for enquiries, the deposit terms on a quote, the three questions you ask before booking a site visit. Those are the lines worth writing down.

• Start from a procedure you already run. The best first skill is the SOP your office manager already follows. Write the steps, the checks and the output, then add the trigger phrases.
• Keep SKILL.md short and push detail down. Price lists, templates and policies go in references or assets, linked once from the main file.
• Give the agent scripts for anything that must be exact. A calculation, a validation, a lookup against your data. Never leave a fragile step to improvisation.
• Make the last step an approval. A skill that drafts a reply, stages a change or prepares a quote for a person to confirm is safe to let the agent trigger on its own. One that sends, publishes or charges is not.

A skill needs something to act on. Scripts run against your data, references describe your systems and assets are your templates. If your website is a page builder with content locked inside layouts, there is little for a skill to read or change. If it is a platform you own, with services, pricing and enquiries stored as data, a skill can look things up, draft the fix and stage it for your approval. That is the difference between an agent that advises and one that does work.

Key takeaways

1. 1

   A Claude skill is a folder with one required file, SKILL.md, plus optional scripts, references and assets folders. The format is an open standard called Agent Skills.

2. 2

   SKILL.md holds a metadata block (a name of up to 64 characters and a description of up to 1,024) followed by plain Markdown instructions, kept under 500 lines.

3. 3

   Skills load in three stages: descriptions at startup, the full SKILL.md on activation, and supporting files only when a step needs them. Scripts are run, not read.

4. 4

   A good business skill is a written procedure with your rules in it, detail pushed into reference files, exact steps handled by scripts, and a person approving the final action.

Frequently asked questions