Complete Guide to Building Claude Skills

Contents Introduction Fundamentals Planning and design7 Testing and iteration14 Distribution and sharing18 Patterns and troubleshooting21 Introduction Askillis a set of instructions - packaged as a simple folder - that teaches Claudehow to handle specific tasks or workflows. Skills are one of the most powerfulways to customize Claude for your specific needs. Instead of re-explaining your Two Paths Through This Guide Building standalone skills? Focus on Fundamentals, Planning and Design, andcategory 1-2. Enhancing an MCP integration? The "Skills + MCP" section andcategory 3 are for you. Both paths share the same technical requirements, but What you'll get out of this guide:By the end, you'll be able to build a functionalskill in a single sitting. Expect about 15-30 minutes to build and test your first Skills are powerful when you have repeatable workflows: generating frontenddesigns from specs, conducting research with consistent methodology, creatingdocuments that follow your team's style guide, or orchestrating multi-step Let's get started. This guide covers everything you need to know to build effective skills - fromplanning and structure to testing and distribution. Whether you're building a What you'll learn: •Technical requirements and best practices forskillstructure•Patterns for standalone skills and MCP-enhanced workflows•Patterns we've seen work well across different use cases Who this is for: •Developers who want Claude to follow specific workflows consistently•Power users who want Claude to follow specific workflows Fundamentals Chapter 1 Fundamentals What is a skill? Composability Claude can load multipleskills simultaneously. Yourskillshould work wellalongside others, not assume it's the only capability available. Askillis a folder containing: •SKILL.md(required): Instructions in Markdown with YAML frontmatter •scripts/(optional): Executable code (Python, Bash, etc.) Portability •references/(optional): Documentation loaded as needed Skills work identically across Claude.ai, Claude Code, and API. Create a skill onceand it works across all surfaces without modification, provided the environment •assets/(optional): Templates, fonts, icons used in output Core design principles For MCP Builders: Skills + Connectors Progressive Disclosure 💡Building standalone skills without MCP? Skip to Planning and Design - you can Skills use a three-level system: •First level (YAML frontmatter):Always loaded in Claude's system prompt.Provides just enough information for Claude to know when eachskillshould If you already have aworking MCP server, you've done the hard part. Skills arethe knowledge layer on top - capturing the workflows and best practices you •Second level (SKILL.md body):Loaded when Claude thinks theskillisrelevant to the current task. Contains the full instructions and guidance. The kitchen analogy •Third level (Linked files):Additional files bundled within theskilldirectorythat Claude can choose to navigate and discover only as needed. MCP provides the professional kitchen:access to tools, ingredients, and This progressive disclosure minimizes token usage while maintaining Skills provide the recipes:step-by-step instructions on how to create something Together, they enable users to accomplish complex tasks without needing to Why this matters for your MCP users Without skills: •Users connect your MCP but don't know what to do next•Support tickets asking "how do I do X with your integration"•Each conversation starts from scratch With skills: •Pre-built workflows activate automatically when needed•Consistent, reliable tool usage•Best practices embedded in every interaction Planning and design Planning and design Start with use cases Common skill use case categories At Anthropic, we’ve observed three common use cases: Before writing any code, identify 2-3 concrete use cases your skill should enable. Category 1: Document & Asset Creation Good use case definition: Used for: Creating consistent, high-quality output including documents,presentations, apps, designs, code, etc. Use Case: ProjectSprint Planning Real example:frontend-design skill(also seeskills for docx, pptx, xlsx, and Steps: 1. Fetch currentproject status from Linear(via MCP)2. Analyze teamvelocity and capacity3. Suggest taskprioritization4. Create tasksin Linear with proper labels and estimates "Create distinctive, production-grade frontend interfaces with high designquality. Use when building web components, pages, artifacts, posters, or Key techniques: •Embedded style guides and brand standards Ask yourself: •Template structures for consistent output •What does a user want to accomplish? •Quality checklists before finalizing •What multi-step workflows does this require? •No external tools required - uses Claude's built-in capabilities •Which tools are needed (built-in or MCP?) •What domain knowledge or best practices should be embedded? Category 2: Workflow Automa