Agent Skills: A Practical Guide to Building Reusable Expertise for Claude

Agent Skills are the cleanest answer yet to a problem every serious Claude user eventually hits: you keep re-explaining the same workflow. The same formatting rules, the same API quirks, the same "no, do it this way" corrections, conversation after conversation. A skill packages that knowledge into a folder Claude loads on its own, exactly when a task calls for it — so the expertise shows up automatically instead of being re-typed every time. This guide walks through what skills are, how they actually load, and how to build one that works.

What an Agent Skill Actually Is

A skill is just a folder with a SKILL.md file at its root. That file has two parts: YAML frontmatter (a name and a description) and a body of Markdown instructions. Optionally, the folder bundles supporting resources — scripts, reference docs, templates. That's the whole format. There's no model to retrain and no application to redeploy; you're handing Claude a set of instructions and the materials to follow them.

The format is an open standard originally developed by Anthropic, which matters more than it sounds: a skill you write once works across Claude.ai, Claude Code, the Claude API, and the Agent SDK — and across other agents that adopt the standard. You're not building against one product surface.

It also helps to be clear on what a skill is not. A tool executes and returns a result. A skill instead prepares the agent to solve a problem — it injects instructions and context that shape how Claude approaches the task, then gets out of the way. Tools do the thing; skills teach Claude how to do the thing.

How Skills Load: Progressive Disclosure

The mechanism that makes skills practical is progressive disclosure — skills reveal themselves in three stages so that having dozens on hand costs almost nothing until one is needed.

• Discovery. At startup, the agent loads only each skill's name and description — just enough to know when it might be relevant. This is the entire context cost of an idle skill.
• Activation. When a task matches a skill's description, the agent reads the full SKILL.md body into context.
• Execution. The agent follows the instructions, loading referenced files or running bundled scripts only as the work demands.

The payoff: you can keep many skills available with a tiny footprint, because the heavy material loads only when the task actually calls for it. This is also why the description is the single most important line you'll write — it's the only thing Claude sees at discovery time, and it alone decides whether the skill ever activates.

Anatomy of a Skill Folder

A typical skill is organized like this:

my-skill/
├── SKILL.md          # required: frontmatter + instructions
├── scripts/          # optional: executable code for deterministic steps
├── references/       # optional: docs loaded into context as needed
└── assets/           # optional: templates, fonts, icons used in output

Each subfolder maps to a stage of disclosure. references/ holds material loaded only when relevant — long format specs, edge-case handling — so the main SKILL.md stays lean. scripts/ holds code Claude can run without reading the whole file into context, which is ideal for repetitive or deterministic work. assets/ holds files that end up in the output, like a document template.

Step 1: Decide What the Skill Should Do

Start narrow and concrete. A good skill captures one repeatable workflow well: "format release notes to our house style," "generate a slide deck from our brand template," "review Terraform for our security rules." If you can't describe the trigger and the output in a sentence each, the scope is still too fuzzy. Write those two sentences down — they become your description and your success test.

Step 2: Write the Frontmatter

The frontmatter is small but load-bearing:

---
name: release-notes-formatter
description: Format raw changelog entries into our house-style release notes. Use whenever the user provides a list of merged changes, a changelog, or commit messages and wants them turned into published release notes — even if they just say "write up these changes."
---

Two practical rules for the description:

• Say what it does and when to use it. Both halves matter, because Claude matches the description against the task to decide whether to activate.
• Lean slightly pushy. Skills tend to under-trigger — Claude skips them when they'd have helped. Naming concrete contexts and phrasings ("even if they just say…") meaningfully improves how reliably the skill fires.

Step 3: Write the Instructions

Write the body as direct, imperative instructions — the steps you'd give a competent new teammate. A few habits that hold up:

• Prefer "why" over a wall of MUSTs. Explaining the reason behind a rule helps Claude generalize to cases your instructions didn't anticipate.
• Keep SKILL.md lean — roughly under 500 lines. When it grows past that, push detail into references/ files and point to them with a clear note on when to read each.
• Define the output format explicitly when it matters. A short, exact template beats a paragraph describing one.
• Show an example or two. A single input → output pair often communicates more than three paragraphs of prose.

Step 4: Add Bundled Resources (When They Earn Their Place)

Reach for the subfolders only when they pull their weight. A long format reference that's irrelevant to most runs belongs in references/, loaded on demand. A fiddly, deterministic transform belongs in scripts/ as code, where it's faster and more reliable than asking Claude to redo the logic each time. A house template belongs in assets/. If a skill is genuinely a few rules, a single SKILL.md is the right and complete answer — don't manufacture structure.

Step 5: Test, Then Tighten

Run the skill on a handful of realistic prompts — the kind a real user would actually type — and read the outputs critically. Did it trigger at all? Did it follow the rules, or drift back to generic behavior? Where it drifts, the fix is almost always in the wording: a vaguer instruction made sharper, a missing edge case added, or a description that didn't quite match how people phrase the request. Revise, rerun, repeat until it's boringly reliable.

A Word on Security

Skills run with real capability — they can include scripts and reach external resources — so treat an untrusted skill the way you'd treat any code you didn't write. Install only from sources you trust (your own, or Anthropic's), and before running a third-party skill, audit every file in the folder: the SKILL.md, the scripts, the references. The same power that makes skills useful is what makes a malicious one dangerous.

Conclusion

Agent Skills turn hard-won, repeated explanation into something Claude carries with it: a folder of instructions, surfaced automatically through progressive disclosure, reusable across every skills-compatible surface. Start with one narrow workflow, write a description that earns its activation, keep the body lean and the resources purposeful, and test until it's dull. The first skill is the hardest; once the shape clicks, you'll find yourself reaching for them anywhere you've been repeating yourself.

This guide covers building a solid single skill; orchestrating many skills, wiring them into subagents, and distributing them across a team are each worth their own deep dive.

Try it: pick one workflow you've explained to Claude more than twice this month, and turn it into a SKILL.md with nothing but a name, a description, and five lines of instructions. Run it on a real task and tighten from there. If you build one, I'd like to hear what workflow you reached for first.

Frequently Asked Questions

What is an Agent Skill? A skill is a folder containing a SKILL.md file — YAML frontmatter plus Markdown instructions — and optional bundled scripts, references, and assets. It packages a repeatable workflow so Claude applies it automatically when a task matches.

How is a skill different from a tool? A tool executes and returns a result. A skill prepares Claude to solve a problem by injecting relevant instructions and context, then lets Claude do the work. Tools act; skills teach.

What is progressive disclosure? It's the three-stage loading model: Claude sees only each skill's name and description at startup (discovery), loads the full SKILL.md when a task matches (activation), and loads referenced files or runs scripts only as needed (execution). It keeps idle skills nearly free in context.

Why isn't my skill triggering? Almost always the description. It's the only thing Claude sees at discovery, so it must state both what the skill does and the concrete contexts and phrasings that should activate it. Skills tend to under-trigger, so a slightly pushy, specific description helps.

How long should SKILL.md be? Keep it lean — roughly under 500 lines. When it grows beyond that, move detail into references/ files and point to them with guidance on when each should be read.

Where can I use skills? The format is an open standard, so a skill works across Claude.ai, Claude Code, the Claude API, and the Agent SDK, plus other agents that support the standard. Build once, reuse everywhere.

What pre-built skills exist? Anthropic ships skills for common document tasks — PowerPoint, Excel, Word, and PDF — that Claude uses automatically when relevant. You can also write and add your own custom skills.

Do I need to bundle scripts and references? No. They're optional. Use scripts/ for deterministic or repetitive logic, references/ for material loaded on demand, and assets/ for files that appear in output. If your skill is a handful of rules, a single SKILL.md is complete on its own.

Are skills safe to install from anywhere? Treat them like code. Install only from trusted sources, and audit every file — SKILL.md, scripts, and references — before running a third-party skill, since a malicious one could misuse its capabilities.