Claude Skills let you package your workflows, domain expertise, and preferences into reusable instruction folders that Claude loads automatically when relevant. The core philosophy: stop repeating yourself and start teaching Claude once. Instead of re-explaining your processes in every conversation, a skill captures that knowledge permanently — and applies it consistently across Claude.ai, Claude Code, and the API.

What Is a Claude Skill?

A skill is a folder containing a single required file — SKILL.md — plus optional supporting directories:

  • scripts/ — executable Python or Bash code that runs without consuming context
  • references/ — additional documentation loaded only as needed
  • assets/ — templates, fonts, or icons used in outputs

Skills are portable: the same skill works identically across Claude.ai, Claude Code, and the API without modification. They’re also composable — Claude can load multiple skills at once, each contributing specialized expertise without interfering with the others.

The Three-Level Progressive Disclosure Architecture

Skills use a three-level loading system designed to minimize token usage while preserving deep expertise:

  • Level 1 — YAML frontmatter: Always loaded into Claude’s system prompt. Contains just enough information for Claude to decide when the skill is relevant — without pulling the full content into context.
  • Level 2 — SKILL.md body: Loaded when Claude determines the skill is applicable. Contains the full workflow instructions, examples, and error handling.
  • Level 3 — Linked files: Additional documents inside the skill folder that Claude navigates and reads only as needed — API guides, reference docs, or detailed examples.

This progressive approach means a skill library of dozens of entries adds minimal overhead until the right skill is needed.

Writing the SKILL.md Frontmatter

The YAML frontmatter is the most critical part of any skill — it determines whether Claude loads it at the right moment.

---
name: sprint-planner
description: Manages sprint planning workflows including task creation, velocity analysis, and capacity planning. Use when user mentions "sprint", "plan tasks", "create tickets", or "sprint planning".
---

Key rules:

  • name must be kebab-case, no spaces, no capitals, matches the folder name
  • description must include both what the skill does and when to trigger it — include specific phrases users would actually say
  • Keep description under 1024 characters; no XML angle brackets (security restriction)
  • Optional fields: allowed-tools (restrict tool access), license, and metadata for author, version, and MCP server info

A vague description like "Helps with projects" will never trigger reliably. A good description names file types, trigger phrases, and the concrete outcome the skill produces.

Three Categories of Skills

Anthropic’s guide identifies three common patterns in the wild:

Document & Asset Creation — Skills that produce consistent, high-quality output: frontend designs from specs, reports following team style guides, presentations from outlines. These rely only on Claude’s built-in capabilities with no external tools needed.

Workflow Automation — Multi-step processes that benefit from consistent methodology. A sprint planning skill, for example, can fetch project status via MCP, analyze team velocity, suggest prioritization, and create tasks — all as a single guided workflow with validation gates between steps.

MCP Enhancement — If you have a working MCP server, skills add the knowledge layer on top. Without a skill, users connect your MCP but don’t know what to do next and prompt inconsistently. With a skill, best practices are embedded: pre-built workflows activate automatically, reducing support burden and improving result consistency.

Testing, Iteration, and Distribution

Effective skills testing covers three areas:

  • Triggering tests — Run 10–20 queries that should activate the skill and verify it loads without explicit invocation. Target: 90% auto-trigger rate.
  • Functional tests — Verify correct outputs, successful API calls, and consistent structure across repeated runs.
  • Performance comparison — Compare the same task with and without the skill enabled; measure tool calls, token consumption, and user corrections required.

The fastest path to a first skill is the skill-creator skill — available in Claude.ai via the plugin directory or for Claude Code. Describe your top 2–3 workflows, and skill-creator generates a properly formatted SKILL.md with frontmatter, trigger phrases, and suggested structure. Expect 15–30 minutes to build and test your first working skill.

For distribution: host the folder on GitHub, upload it to Claude.ai via Settings > Capabilities > Skills, or deploy organization-wide through enterprise managed settings (available since December 2025). For programmatic use, the /v1/skills API endpoint enables skills in production pipelines and agent systems via the container.skills parameter on the Messages API.

Skills are published as an open standard — portable across tools and platforms by design. Explore Anthropic’s public skills repository for production-ready examples across document creation, workflow automation, and partner integrations from Asana, Figma, Sentry, Zapier, and more. The complete guide and the introductory course are the best starting points to go deeper.