Claude Skills: The Complete Guide to Building, Testing, and Sharing Skills for Claude

Claude Skills are folders of instructions that teach Claude how to handle a specific task or workflow. Instead of re-explaining your preferences, processes, and domain knowledge in every new conversation, you write them down once. From then on, Claude applies them automatically every time the task comes up.

Skills earn their keep on repeatable work: generating frontend designs from specs, running research with a consistent methodology, producing documents that follow your style guide, or orchestrating multi-step processes across tools. For product teams, that covers a lot of ground: PRD templates, feedback triage, sprint planning, release notes.

This guide distills Anthropic's official guidance on building skills into a practical walkthrough: what skills are, how to structure one, how to test it, and how to share it with your team. By the end, you will be able to build a working skill in a single sitting.

What Are Claude Skills?

A skill is a folder. That is the whole format. The folder contains one required file, SKILL.md, which holds instructions in Markdown with a YAML frontmatter header. Three optional directories carry anything the instructions need: executable scripts, reference documentation, and assets like templates or fonts.

your-skill-name/
├── SKILL.md          # Required: instructions + YAML frontmatter
├── scripts/          # Optional: executable code (Python, Bash)
├── references/       # Optional: docs Claude loads as needed
└── assets/           # Optional: templates, fonts, icons

Three design principles shape the format:

• Progressive disclosure. Claude loads skill content in stages, so enabled skills cost almost nothing until they are needed. More on this below.
• Composability. Claude can load multiple skills at once. A well-built skill works alongside others instead of assuming it is the only capability available.
• Portability. Skills work identically across Claude.ai, Claude Code, and the Claude API. Build once, run everywhere, provided the environment supports the skill's dependencies.

Anthropic has also published Agent Skills as an open standard, in the same spirit as MCP. The format is designed to be portable across AI platforms, and authors can flag platform-specific requirements in an optional compatibility field.

How Claude Skills Work: Progressive Disclosure

If every enabled skill dumped its full contents into every conversation, skills would bloat context and degrade responses. The format avoids this with a three-level loading system:

1. YAML frontmatter. Always loaded into Claude's system prompt. It carries just enough for Claude to know when the skill applies: a name and a description.
2. SKILL.md body. Loaded only when Claude decides the skill is relevant to the current task. This is where the full instructions live.
3. Linked files. Scripts, references, and assets that Claude navigates to only as needed.

This is why the description field matters so much. It is the only part of your skill Claude sees before deciding whether to load the rest.

Claude Skills vs MCP: What Is the Difference?

Anthropic's analogy: MCP provides the professional kitchen, with access to tools, ingredients, and equipment. Skills provide the recipes. MCP connects Claude to your services (Notion, Linear, your own API) and gives it real-time data access and tool invocation. Skills capture the workflows and best practices for using those tools well.

Put simply: MCP defines what Claude can do. Skills define how Claude should do it.

If you already run an MCP server, you have done the hard part, and the gap shows up in predictable ways. Users connect the integration and stall on what to do next. Every conversation starts from scratch. Results vary because everyone prompts differently. Support tickets ask 'how do I do X with your integration'. A skill fixes all of it at once: pre-built workflows activate automatically, tool usage becomes consistent, and best practices ship inside every interaction.

When to Build a Claude Skill: 3 Use Case Categories

Anthropic has observed three categories that cover most skills in production.

1. Document and asset creation

Consistent, high-quality output: documents, presentations, designs, code. Anthropic's frontend-design skill and its docx, pptx, and xlsx skills sit in this bucket. Typical techniques: embedded style guides and brand standards, template structures, and a quality checklist the output must pass before it ships. No external tools required; these run entirely on Claude's built-in capabilities.

2. Workflow automation

Multi-step processes that benefit from consistent methodology, including work that spans multiple MCP servers. The skill-creator skill is the reference example: it walks you through use case definition, frontmatter generation, instruction writing, and validation, with checkpoints at each step.

3. MCP enhancement

Workflow guidance layered on top of an MCP server's tool access. Sentry's code-review skill analyzes and fixes bugs detected in GitHub pull requests using Sentry's error monitoring data via their MCP server. Typical techniques: coordinating multiple MCP calls in sequence, embedding domain expertise, and handling common MCP errors so users never have to.

How to Build Your First Claude Skill, Step by Step

Step 1: Define 2 or 3 concrete use cases

Before writing anything, pin down what the skill should enable. Anthropic recommends writing each use case in this shape:

Use case: Sprint planning
Trigger: User says "help me plan this sprint" or "create sprint tasks"
Steps:
  1. Fetch current project status from Linear (via MCP)
  2. Analyze team velocity and capacity
  3. Suggest task prioritization
  4. Create tasks in Linear with labels and estimates
Result: Fully planned sprint with tasks created

Four questions to answer for each: what does the user want to accomplish, what multi-step workflow does it require, which tools are involved (built-in or MCP), and what domain knowledge should be embedded.

Step 2: Create the folder and SKILL.md

The naming rules are strict. The file must be named exactly SKILL.md, case-sensitive, no variations. The folder must be kebab-case: notion-project-setup works; spaces, underscores, and capitals all fail validation. Do not put a README.md inside the skill folder; documentation belongs in SKILL.md or references/.

The minimal viable skill is a folder plus this frontmatter:

---
name: your-skill-name
description: What it does. Use when the user asks to [specific phrases].
---

Step 3: Write a description that triggers

The description is the highest-leverage line in the file, because it is the only thing Claude reads when deciding whether to load your skill. It must say both what the skill does and when to use it, in under 1,024 characters. Include the specific phrases users say.

# Good: specific, with trigger phrases
description: Manages Linear project workflows including sprint
  planning, task creation, and status tracking. Use when the user
  mentions "sprint", "Linear tasks", "project planning", or asks
  to "create tickets".

# Bad: too vague to ever trigger
description: Helps with projects.

Two security restrictions apply because frontmatter lands in Claude's system prompt: no XML angle brackets anywhere in it, and no skills named with 'claude' or 'anthropic' (both are reserved).

Step 4: Write instructions Claude can follow

Below the frontmatter, write the instructions in plain Markdown: numbered steps, a few worked examples, and a troubleshooting section for known failure modes. Two habits separate skills that work from skills that frustrate:

• Be specific and actionable. 'Validate the data before proceeding' gives Claude nothing. 'Run python scripts/validate.py --input {filename}, and if validation fails check for missing required fields and invalid date formats' gives it a procedure.
• Keep SKILL.md lean. Core instructions stay in SKILL.md; detailed API docs, edge cases, and long examples move to references/ with a clear pointer to when each file should be consulted. Anthropic recommends keeping SKILL.md under 5,000 words.

For validations that must never be skipped, bundle a script in scripts/ and instruct Claude to run it rather than describing the check in prose.

Code is deterministic; language interpretation isn't.

Step 5: Define success criteria

Decide upfront how you will know the skill works. Anthropic frames these as rough benchmarks rather than precise thresholds: the skill triggers on roughly 90% of relevant queries, completes the workflow in fewer tool calls than an unassisted baseline, and produces zero failed API calls per run. On the qualitative side: users should not need to prompt Claude about next steps, and the same request should produce structurally consistent results across sessions.

How to Test Claude Skills

Testing rigor should match the skill's blast radius. Anthropic describes three levels: manual testing in Claude.ai (run queries, observe behavior, fast iteration), scripted testing in Claude Code (repeatable test cases across changes), and programmatic evaluation via the skills API (systematic suites against defined test sets). A skill used by a team of three needs less ceremony than one shipped to thousands of users.

Effective testing covers three areas.

Triggering tests

Verify the skill loads at the right times: it should fire on obvious requests and on paraphrases, and stay silent on unrelated topics.

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"

A useful debugging trick: ask Claude 'when would you use the [skill name] skill?' It will quote your description back, which shows you exactly what is missing from it.

Functional tests

Verify the skill produces correct output: valid results, successful API calls, working error handling, edge cases covered. Write them given/when/then style: given a project name and five task descriptions, when the skill runs, then the project exists, five tasks are created with correct properties and linked to it, and no API errors occurred.

Performance comparison

Prove the skill beats the baseline. In Anthropic's example comparison, the same workflow without the skill took 15 back-and-forth messages, 3 failed API calls, and 12,000 tokens. With the skill: automatic execution, 2 clarifying questions, 0 failed calls, and 6,000 tokens.

Iterating after launch

Skills are living documents. Undertriggering (the skill fails to load when it should, users enable it manually) means the description needs more detail and keywords, especially technical terms. Overtriggering (it loads for irrelevant queries, users disable it) means you need negative triggers and a narrower scope:

description: Advanced data analysis for CSV files. Use for
  statistical modeling, regression, clustering. Do NOT use for
  simple data exploration (use the data-viz skill instead).

5 Claude Skill Patterns That Work

These patterns come from skills built by early adopters and Anthropic's internal teams. Before picking one, decide which way your skill faces. Problem-first skills start from an outcome ('set up a project workspace') and orchestrate whatever tools it takes. Tool-first skills start from access ('Notion MCP is connected') and teach Claude the optimal workflows. Most skills lean one direction.

1. Sequential workflow orchestration

For multi-step processes with a fixed order, like onboarding a customer: create the account, set up payment, create the subscription, send the welcome email. Make the ordering explicit, name the dependencies between steps (the subscription needs the customer ID from step 1), validate at each stage, and include rollback instructions for failures.

2. Multi-MCP coordination

For workflows spanning several services, like a design-to-development handoff: export assets from Figma, store them in Drive, create Linear tasks with the links attached, then post a summary to Slack. Separate the phases clearly, define what data passes between them, and validate before moving to the next phase.

3. Iterative refinement

For output that improves with revision, like report generation: draft, run a validation script, fix the issues it finds, regenerate the affected sections, and repeat until the quality bar is met. State explicit quality criteria and, critically, when to stop iterating.

4. Context-aware tool selection

For one outcome with several possible tools, like file storage: large files go to cloud storage, collaborative docs to Notion, code to GitHub. Give Claude a decision tree with clear criteria, fallback options, and an instruction to tell the user why it chose what it chose.

5. Domain-specific intelligence

For skills whose value is expertise rather than orchestration, like payment processing under compliance rules: check sanctions lists and jurisdiction allowances before processing, flag failures for review instead of proceeding, and log every decision for the audit trail. The knowledge in the skill is the product; the tool calls are plumbing.

Troubleshooting Claude Skills

The skill fails to upload

'Could not find SKILL.md': the file is not named exactly SKILL.md (case-sensitive). 'Invalid frontmatter': usually missing --- delimiters or an unclosed quote in the YAML. 'Invalid skill name': the name has spaces or capitals; rename it to kebab-case.

The skill never triggers

Rewrite the description. Check three things: is it too generic ('helps with projects' will never fire), does it include phrases users would say, and does it mention relevant file types. Then use the debugging trick above to see what Claude thinks the skill is for.

The skill triggers too often

Add negative triggers naming what the skill is not for, tighten the scope ('processes PDF legal documents for contract review' beats 'processes documents'), and point to the alternative skill users should reach for instead.

The skill loads but Claude ignores the instructions

Three common causes. Instructions too verbose: cut prose, use numbered lists, move detail to references/. Critical points buried: put them at the top under an '## Important' header and repeat them if needed. Ambiguous language: 'make sure to validate things properly' is not an instruction; list the exact checks. For checks that must never be skipped, bundle a validation script.

Responses feel slow or degraded

The context is overloaded. Trim SKILL.md (keep it under 5,000 words), move documentation to references/, and check how many skills are enabled at once. Anthropic suggests reviewing your setup once you pass the 20 to 50 mark.

How to Share and Distribute Claude Skills

For individuals: zip the skill folder and upload it in Claude.ai under Settings, then Capabilities, then Skills, or drop the folder into your Claude Code skills directory. For organizations: since December 2025, admins can deploy skills workspace-wide with centralized management and automatic updates.

For production systems, the API gives you direct control: a /v1/skills endpoint for managing skills, a container.skills parameter to attach them to Messages API requests, and versioning through the Claude Console. Skills in the API require the Code Execution Tool beta, and they work with the Claude Agent SDK. The rule of thumb: humans iterating on workflows belong in Claude.ai or Claude Code; applications and automated pipelines belong on the API.

If you distribute publicly, host the skill on GitHub with a repo-level README, installation steps, and screenshots (the README lives in the repo, never inside the skill folder). If you ship an MCP server, link the skill from your MCP docs and explain why the two are better together. And when you write about it, sell the outcome, not the file format: 'sets up a complete project workspace in seconds instead of 30 minutes of manual setup' beats 'a folder containing YAML frontmatter and Markdown instructions'.

Start With One Workflow

Resist the urge to encode everything your team knows on day one. Pick one workflow you repeat every week, write down 2 or 3 concrete use cases, and build the smallest skill that handles them. Test that it triggers, run it against real tasks, and sharpen the description based on what you see.

The teams that get the most out of skills treat them like code: versioned, reviewed, and improved every time a run goes sideways. One well-built skill that fires reliably beats ten that half-work. Start with one.