What Are Claude Agent Skills? The Reusable Workflow Feature, Explained

Skills Are Folders, Not a New API

A Claude Skill is, at its core, unglamorous: a folder containing a Markdown file (SKILL.md) with instructions, plus optional scripts and reference documents Claude can pull in when needed. Anthropic frames them as "custom onboarding materials that let you package expertise" — the same kind of walkthrough you'd hand a new hire, except Claude actually reads and follows it every time, without drifting or forgetting.

What makes this different from just pasting instructions into a chat is that Skills are composable and portable. They stack — Claude can pull in a brand-guidelines Skill and a PowerPoint Skill in the same task, deciding on its own which ones apply. And once built, a Skill works everywhere Claude does: the Claude apps, Claude Code, and the API, using the same file format across all three.

Progressive Disclosure: Why Skills Don't Bloat Your Context

Only a Skill's short description sits in context by default — the full instructions load only when a task actually needs them.

The traditional way to extend an AI agent is prompt stuffing: cram every possible instruction, edge case, and template into the system prompt so the model has it on hand. That approach gets expensive and confusing fast — a system prompt covering both Kubernetes troubleshooting and Python style guides becomes a bloated mess that slows inference and muddies which rules apply when.

Skills solve this with progressive disclosure. At the start of a session, Claude scans the frontmatter of every available Skill — just the name and a short description, on the order of a hundred tokens each. Only when a task actually matches does Claude load the full SKILL.md content, which can run up to a few thousand words, along with any linked scripts or reference files. A Skill you never use costs almost nothing; a Skill you do use loads exactly once, right when it's relevant.

How Skills Differ From Projects and MCP

Anthropic's ecosystem now has three overlapping-but-distinct ways to customize Claude, and it's easy to conflate them. Skills, Projects, and MCP solve different problems, and the strongest setups usually combine more than one.

In practice, a well-built agent often uses all three: an MCP server to pull live ticket data, a Project holding the client's account history, and a Skill defining exactly how the weekly status report should be formatted. Skills are the layer that makes the output consistent, no matter which model checkpoint or session is doing the writing.

Building Your First Skill

Anthropic's own anthropic/skills GitHub repository is the standard place to start — it holds official examples like skill-creator, an interactive tool that walks you through structuring a new Skill, alongside document-handling Skills you can study for formatting conventions. A community-curated collection, awesome-claude-skills, adds hundreds more covering everything from text cleanup to browser automation with Playwright.

The frontmatter of a SKILL.md file matters more than it looks. The description field is the only signal Claude has to decide whether a Skill is relevant to a given task — vague descriptions mean Claude either loads Skills it doesn't need or misses ones it should have used. Specific, task-oriented descriptions ("formats quarterly sales reports to match the Q1 2026 template, including chart placement") consistently outperform generic ones ("helps with reports").

That last point trips up a lot of first-time builders: a Skill can test perfectly inside a live conversation and still fail once packaged into a downloadable ZIP, usually because of a misnamed file or a broken internal reference. Testing the packaged version — not just the in-chat draft — before relying on a Skill for real work is worth the extra five minutes.

Is It Worth Building Your Own?

Frequently Asked Questions