Claude Skills Explained: How They Work and How to Build One

Claude skills are the most practical thing Anthropic has shipped for teams that want Claude to do real, repeatable work instead of just answering questions. If you're evaluating Claude for workflow automation, document generation, or agentic tasks, skills are the feature that separates "interesting demo" from "actually useful in production."

The short version: Claude skills are structured expertise packages (folders containing instructions, scripts, and resources) that Claude loads dynamically when a task matches. They turn a general-purpose model into a reliable specialist for specific workflows. Anthropic's own Claude Cookbook describes them as "organized packages of instructions, executable code, and resources that give Claude specialized capabilities for specific tasks." That definition is accurate, but it undersells what they actually enable.

This guide covers how skills work, how to write one that installs cleanly on claude.ai, Claude Code and the API, and where they fall short.

What Are Claude Skills?

A skill is a folder. That's the mental model. Inside that folder lives a required SKILL.md file written in Markdown with YAML frontmatter, plus optional subdirectories for scripts, references, and assets. Once you add that folder to Claude, it becomes a reusable capability that Claude can invoke automatically whenever a conversation calls for it.

The Claude Help Center puts it plainly: skills "teach Claude how to complete specific tasks in a repeatable way, whether that's creating documents with your company's brand guidelines, analyzing data using your organization's specific workflows, or automating personal tasks."

So what makes this different from a system prompt or a saved custom instruction? Scope and efficiency. A system prompt loads every time, regardless of relevance. A skill's full instructions load only when Claude determines they're needed, based on the skill's name and description.

Prompts vs. Skills

Traditional prompting is one-off. You write a prompt, Claude executes it, the context disappears. Next session, you start over. For simple queries that's fine. For anything repeatable, it's a tax you pay every time.

Skills encode the workflow once: instructions, examples, guardrails and step-by-step logic for one type of task. Once a skill is installed, Claude loads that logic on demand without you re-explaining it. The Department of Product newsletter describes them as "just folders that contain information that Claude can load whenever it thinks they might be relevant" that tell Claude "how to complete a task, such as generating a report, a presentation or a coding task in a repeatable way that is customized to your own company's needs."

Folder Structure

A well-built skill folder typically looks like this:

The frontmatter carries the two fields Claude matches against, name and description, and the description has to say both what the skill does and when to use it. The body of the file contains the actual instructions, workflow stages, and examples.

How Skills Load

Claude doesn't load every skill for every message. At startup it sees only each skill's name and description, about 100 tokens per skill according to Anthropic's Agent Skills overview. When a request matches a description, Claude reads the SKILL.md body, and it opens bundled files only when those instructions point to them. Scripts run without their code entering the context window; only their output does. Anthropic calls this progressive disclosure, and it's the mechanism that prevents context window overload when you have multiple skills installed.

That's why the description matters so much: a vague one means missed triggers, a precise one means reliable activation.

Types of Skills

Anthropic's Pre-Built Agent Skills

Anthropic ships four official Agent Skills covering the most common document workflows:

• Excel (xlsx): creates spreadsheets, analyzes data, generates reports with charts
• PowerPoint (pptx): creates presentations, edits slides, analyzes presentation content
• Word (docx): creates documents, edits content, formats text
• PDF (pdf): generates formatted PDF documents and reports

These are available via the Claude API, Claude Platform on AWS, Microsoft Foundry, and claude.ai. For teams that need consistent document outputs without building custom skills from scratch, these are the fastest starting point.

Custom User Skills

As of September 2026, users on the Free, Pro, Max, Team and Enterprise plans can upload their own skills on claude.ai under Customize > Skills, with code execution turned on: write your SKILL.md, zip the folder, upload it (setup for each surface is below). From that point, Claude invokes it automatically in relevant conversations.

And this is where the real flexibility lives. You can encode any repeatable workflow you run regularly, whether that's a content brief template, a client onboarding checklist, a code review process, or a data analysis pipeline.

Organization and Partner Skills

On Team and Enterprise plans, owners can provision skills for every member and decide whether members can share skills with colleagues or publish them to the organization's library. This is where skills start functioning as a governance tool, not just a productivity one. When an organization embeds brand guidelines, compliance rules, and approved workflows into shared skills, every team member gets the same playbook, and owner-provisioned skills are switched on by default. Partner skills in the Skills Directory come from companies such as Notion, Figma and Atlassian and are built to work with their MCP connectors.

What Skills Actually Enable

Documents and Presentations

The PowerPoint and Word skills handle the mechanical work of creating structured documents. Pair them with a custom skill that holds your brand guidelines and templates, and Claude produces slide decks or reports that follow your formats, not its defaults. For product and strategy teams that generate stakeholder presentations regularly, that cuts the reformatting cycle that eats time after every AI-generated draft.

Data Analysis

The Excel skill creates spreadsheets, analyzes data, and generates reports with charts. The practical shift is from describing what you want in every prompt to invoking a skill that already knows your reporting format.

Multi-Step Agentic Workflows

A skill can encode a full multi-step process with explicit stages, tool calls, and guardrails. Chris Lema's Expert Profiler skill walkthrough is a clear public example. His SKILL.md defines four discrete stages: identity discovery, content collection, profile synthesis, and delivery. As he puts it, "SKILL.md is the workflow." Claude searches for the person, stops to confirm it found the right one, collects their public posts and interviews through Apify's MCP server, and delivers a ten-section profile as a markdown file.

That's agent-like behavior driven by a structured skill, not by a complex orchestration framework. Lema notes that the same SKILL.md works in both claude.ai and Claude Code.

Technical Details

SKILL.md and Trigger Conditions

Here's a minimal SKILL.md for a recurring reporting job, saved in a folder named weekly-ad-report with its two reference files under references/:

---
name: weekly-ad-report
description: Builds the weekly paid media report from Meta Ads and Google Ads CSV exports, with spend, CPA and ROAS by campaign. Use when the user shares ad platform exports or asks for a weekly ad report.
---

# Weekly ad report

1. Read each CSV the user shares. Match column names using references/columns.md.
2. Total spend, conversions and revenue by campaign. CPA = spend / conversions. ROAS = revenue / spend.
3. Flag any campaign whose CPA is more than 20% above the account average.
4. Write a short summary, a campaign table and next actions, following references/template.md.

The description is the trigger: Claude matches each request against it, so it must say what the skill does and when to use it, in the third person. The rules, per Anthropic's skill authoring guide and product docs:

• name: lowercase letters, numbers and hyphens, up to 64 characters, without "anthropic" or "claude". The folder must use the same name; a mismatch is a common upload error.
• description: required, no XML tags. The Skills API accepts up to 1,024 characters, but Anthropic's claude.ai guide to custom skills gives 200 as the maximum, so stay under 200 if the skill will go to claude.ai.
• Only six keys for uploads: per Claude Code's skills docs, claude.ai uploads and the Skills API accept only name, description, license, compatibility, metadata and allowed-tools, and reject any other key. when_to_use is a Claude Code-only field, so trigger wording goes in description.

One YAML trap: an unquoted value containing a colon followed by a space won't parse, so quote the description if it needs one.

Skills and MCP Together

Skills and MCP (Model Context Protocol) serve different functions and work well together. MCP connects Claude to external services such as Notion, Asana and Linear. Skills teach Claude how to use those connections for a specific workflow. The practical division: MCP opens the door to a service, the skill tells Claude what to do once it's inside.

For a reporting workflow, MCP might pull live data from a project management tool, while the skill encodes the analysis logic, formatting rules, and output structure. Neither does the full job alone. The same split applies to Meta's ads MCP server: the server connects Claude to your ad account, and a skill can hold your draft-then-confirm routine.

Stacking Skills

Claude can use several skills in one task. Skills can't call each other directly, but Claude combines the ones that match. Because an idle skill costs only its name and description in context, a library of small, focused skills stays cheap. On the API, a request can include up to 20 skills, and Anthropic advises leaving out any a request doesn't need.

You don't need one monolithic skill that tries to do everything. Build modular skills for discrete workflow components and let Claude compose them.

Real-World Use Cases

Operations Teams

Operations use cases center on SOPs and recurring reporting. Put your standard operating procedures in a skill's reference files and the workflow stages in SKILL.md, and Claude follows your process rather than improvising one. For a weekly or monthly reporting cycle, that's the difference between a tool you configure each time and one that already knows the job, the same systematizing idea behind the GTD for Digital Marketing campaign workflow.

Developers and Technical Teams

Developer-oriented skills can combine scripts, reference documentation, and MCP tool connections for multi-step technical tasks: code scaffolding, PR review checklists, deployment runbooks, API integration patterns. The scripts/ subdirectory is particularly useful here, because it packages executable code alongside the instructions that govern when and how Claude runs it. If you're already comparing AI coding tools, the Claude Code vs Cursor vs Windsurf breakdown is worth reading alongside this.

Building Your Own Skill

From Idea to SKILL.md

1. Define the task. One specific, repeatable workflow.
2. Outline the stages. Discrete steps with clear inputs and outputs.
3. Write the frontmatter. A valid name and a description that says what the skill does and when to use it.
4. Write the instructions. What Claude should ask, produce and check at each step. Anthropic suggests keeping the body under 500 lines and moving detail into separate files.
5. Add examples of good output.
6. Package supporting files in subfolders and point to them from SKILL.md.
7. Install it on each surface where you'll use it (below).

The complete guide from Anthropic covers this in detail and is worth reading before you build anything non-trivial. It dates from January 2026, so check its menu paths against the Help Center.

Where Skills Live

Paths and limits as of September 2026:

• claude.ai: turn on code execution first ("Code execution and file creation" in Settings > Capabilities on Free, Pro and Max; on Team and Enterprise an owner controls it and Skills in Organization settings > Plugins & skills). Zip the folder so the folder itself sits at the root of the ZIP, then go to Customize > Skills, click "+", choose "Create skill" and "Upload a skill".
• Claude Code: nothing to upload. Save the folder in ~/.claude/skills/ for all your projects, or in a repository's .claude/skills/ and commit it for your team. Signed in with your claude.ai account (v2.1.273 or later), Claude Code also syncs the skills enabled there.
• Claude API: upload the folder or a ZIP (under 30 MB uncompressed) to the Skills API with POST /v1/skills, then pass its skill_id in the Messages API container parameter with the code execution tool, on a model that supports it (the Claude API models guide covers choosing one). Custom skills are shared across the workspace, and the container has no network access.

Uploads don't sync between claude.ai and the API, so upload a skill to each one you use.

Writing Clear Instructions

The Expert Profiler skill is a useful template for structure. Each stage has a clear purpose, a defined action, and a specific output. Guardrails are explicit: the file spells out the questions Claude asks, the point where it waits for the user to confirm, and the tools each stage uses.

Vague instructions produce inconsistent results. If your skill's instructions say "analyze the data and produce a report," you'll get different outputs every time. If they say "calculate the rolling moving average, identify the top three anomalies by standard deviation, and format the output as a three-section report with an executive summary, findings table, and recommended actions," you'll get consistency.

Testing and Iteration

Test your skill across multiple conversations with different inputs before treating it as production-ready. The description is the first thing to validate: does Claude invoke the skill when it should? Does it stay dormant when the task is unrelated? On claude.ai, Claude's thinking shows whether it loaded the skill; in Claude Code, /skills lists what's installed and /weekly-ad-report runs it directly. After that, test the workflow stages for edge cases, inputs that are ambiguous, incomplete, or outside the expected format.

Refine the instructions based on where Claude deviates from what you expected, and tighten the examples to cover the cases that caused problems.

Strengths and Limitations

Where Skills Work Well

Skills genuinely deliver on consistency and efficiency for repeatable workflows. The token efficiency argument is real: loading only the relevant skill instructions for a task, rather than stuffing everything into a system prompt, keeps context lean and outputs focused.

Where They Fall Short

Skills are only as good as their instructions. A poorly designed SKILL.md with vague stages and weak examples will produce inconsistent results, and the skill format won't fix that. The trigger matching also depends on a good description: if yours is vague, Claude will either miss relevant tasks or invoke the skill when it shouldn't.

Skills can also run code, so Anthropic's advice is to install them only from sources you trust and to read every file in one before you enable it.

There's also a maintenance consideration. Skills that reference internal brand guidelines or compliance rules need to stay current. An outdated skill that still references deprecated processes is worse than no skill, because it confidently applies the wrong rules.

Governance and Versioning

For organizations provisioning skills centrally, version control matters. Treat skill files the same way you'd treat internal documentation: assign ownership, establish an update process, and audit periodically. The governance benefit of shared skills only holds if the skills themselves reflect current standards.

Frequently Asked Questions

Where This Is Heading

Anthropic is clearly building toward Claude as a task-oriented agent, not just a chat interface, and skills are the infrastructure for that shift: your processes in skills, live data through MCP, and the pre-built skills for common documents.

The format is also an open standard, published at agentskills.io, so a skill you write isn't locked to Claude.

Honestly, the underlying principle here isn't new. Encode your best process once, let Claude execute it reliably every time. That's been the promise of automation for decades. But Claude skills make it accessible without requiring a full engineering investment. For teams that have been treating Claude as a smart search box, skills are the upgrade worth taking seriously.

← Back to the blog