The Complete Guide
to Building Skills
for Claude

Claude logo

The logo for Claude, featuring a white stylized asterisk or starburst icon to the left of the word "Claude" in a dark serif font.

Claude logo

Contents

Introduction 3
Fundamentals 4
Planning and design 7
Testing and iteration 14
Distribution and sharing 18
Patterns and troubleshooting 21
Resources and references 28

Introduction

A skill is a set of instructions - packaged as a simple folder - that teaches Claude how to handle specific tasks or workflows. Skills are one of the most powerful ways to customize Claude for your specific needs. Instead of re-explaining your preferences, processes, and domain expertise in every conversation, skills let you teach Claude once and benefit every time.

Skills are powerful when you have repeatable workflows: generating frontend designs from specs, conducting research with consistent methodology, creating documents that follow your team's style guide, or orchestrating multi-step processes. They work well with Claude's built-in capabilities like code execution and document creation. For those building MCP integrations, skills add another powerful layer helping turn raw tool access into reliable, optimized workflows.

This guide covers everything you need to know to build effective skills - from planning and structure to testing and distribution. Whether you're building a skill for yourself, your team, or for the community, you'll find practical patterns and real-world examples throughout.

What you'll learn:

Who this is for:

Two Paths Through This Guide

Building standalone skills? Focus on Fundamentals, Planning and Design, and category 1-2. Enhancing an MCP integration? The "Skills + MCP" section and category 3 are for you. Both paths share the same technical requirements, but you choose what's relevant to your use case.

What you'll get out of this guide: By the end, you'll be able to build a functional skill in a single sitting. Expect about 15-30 minutes to build and test your first working skill using the skill-creator.

Let's get started.

A diagram showing two white shapes on a green background. On the left is a white octagon with a black dot at its center. On the right is a white equilateral triangle with a black dot at its center. A thick black line connects the center dot of the octagon to the center dot of the triangle.
A diagram showing two white shapes on a green background. On the left is a white octagon with a black dot at its center. On the right is a white equilateral triangle with a black dot at its center. A thick black line connects the center dot of the octagon to the center dot of the triangle.

Fundamentals

What is a skill?

A skill is a folder containing:

Core design principles

Progressive Disclosure

Skills use a three-level system:

This progressive disclosure minimizes token usage while maintaining specialized expertise.

Composability

Claude can load multiple skills simultaneously. Your skill should work well alongside others, not assume it's the only capability available.

Portability

Skills work identically across Claude.ai, Claude Code, and API. Create a skill once and it works across all surfaces without modification, provided the environment supports any dependencies the skill requires.

For MCP Builders: Skills + Connectors

💡 Building standalone skills without MCP? Skip to Planning and Design - you can always return here later.

If you already have a working MCP server , you've done the hard part. Skills are the knowledge layer on top - capturing the workflows and best practices you already know, so Claude can apply them consistently.

The kitchen analogy

MCP provides the professional kitchen: access to tools, ingredients, and equipment.

Skills provide the recipes: step-by-step instructions on how to create something valuable.