Claude Official Skills - Complete Guide: Building Your AI Skill Pack from Zero to One

Introduction

Skill is a practical extension mechanism in the Claude ecosystem—simply put, it's a folder that solidifies "how you want Claude to work." No need to re-explain your preferences, workflows, and expertise every conversation—teach once, and it's done.

This guide is an official Anthropic tutorial covering Skill basics to design, testing, deployment, and five practical patterns with troubleshooting.

Chapter 1: Core Concepts

What is a Skill?

A Skill is a folder containing:

SKILL.md (required): Markdown instruction file with YAML frontmatter
scripts/ (optional): Executable code (Python, Bash, etc.)
references/ (optional): Reference documents loaded on demand
assets/ (optional): Templates, fonts, icons and other output resources

Three Core Design Principles:

Progressive Disclosure: Three-layer system for information loading—YAML frontmatter (always loaded), SKILL.md body (loaded when relevant), associated files (loaded only when needed)
Composability: Multiple Skills can be loaded simultaneously; design yours to coexist peacefully
Portability: Skills work consistently across Claude.ai, Claude Code, and API

MCP + Skills Relationship:

MCP provides the connection layer (what Claude can do), while Skills provide the knowledge layer (how Claude should do it). Think of MCP as a professional kitchen with all the tools, and Skills as the recipes.

Chapter 2: Planning and Design

Start with Use Cases:

Before writing code, define 2-3 specific use cases your Skill will support. Ask yourself: What does the user want to accomplish? What multi-step workflows are needed? What tools are required? What domain knowledge should be embedded?

Three Common Use Case Categories:

Category 1: Document & Asset Creation—Creating consistent, high-quality outputs like documents, presentations, apps, designs, code. Example: frontend-design Skill
Category 2: Workflow Automation—Multi-step processes benefiting from unified methodology. Example: skill-creator Skill
Category 3: MCP Enhancement—Adding workflow guidance to MCP server tools. Example: sentry-code-review Skill

YAML Frontmatter—The Critical Part:

Minimum required format:

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

Writing Good Descriptions:

Structure: [What it does] + [When to use] + [Core capabilities]

Include specific trigger phrases users might say. Mention specific file types if relevant. Keep under 1024 characters.

Chapter 3: Testing and Iteration

Three Testing Levels:

Claude.ai Manual Testing: Run queries directly to observe behavior. Fast iteration, no setup needed.
Claude Code Script Testing: Automated test cases, repeatable verification after code changes.
Skills API Programmatic Testing: Build evaluation suites for systematic validation.

Three Types of Tests:

Trigger Testing: Ensure Skill loads at the right time
Functional Testing: Verify Skill produces correct results
Performance Comparison: Prove Skill actually improves results

Using skill-creator:

skill-creator is an Anthropic tool available in Claude.ai and Claude Code. Use it by saying: "Use the skill-creator skill to help me build a skill for [your use case]"

Iteration Signals:

Under-triggering: Add more details and keywords to description
Over-triggering: Add negative trigger conditions, narrow scope
Execution issues: Improve instructions, add error handling

Chapter 4: Distribution and Sharing

Current Distribution Methods:

Personal User Installation: Download Skill folder → Upload via Claude.ai Settings > Capabilities > Skills, or place in Claude Code skills directory
Organization-level Skills: Admins can deploy Skills workspace-wide with auto-updates and centralized management

Open Standard:

Anthropic has published Agent Skills as an open standard. Skills should work across tools and platforms—same Skill runs on Claude or other AI platforms. Use compatibility field to note platform-specific requirements.

Using Skills via API:

/v1/skills endpoint for listing and managing Skills
Add Skills via container.skills parameter in Messages API
Version control in Claude Console
Integrate with Claude Agent SDK for custom agents

Chapter 5: Patterns and Troubleshooting

5 Proven Patterns:

Pattern 1: Sequential Workflow Orchestration—Multi-step processes in specific order
Pattern 2: Multi-MCP Coordination—Workflows spanning multiple services
Pattern 3: Iterative Refinement—Output quality improved through iteration
Pattern 4: Context-aware Tool Selection—Different tools for same goal in different contexts
Pattern 5: Domain Expertise Embedding—Adding professional knowledge beyond tool access

Troubleshooting Guide:

Upload failures: Check SKILL.md naming (case-sensitive), validate YAML format, ensure skill name uses kebab-case
Skill not triggering: Make description more specific, include trigger phrases, mention file types
Over-triggering: Add negative triggers, narrow scope, be more specific
MCP connection issues: Verify MCP server connected, check authentication, test MCP independently
Instructions not followed: Keep instructions concise, place key instructions at top, use explicit validation steps

Chapter 6: Resources and References

Official Documentation:

Best Practices Guide
Skills Documentation
API Reference
MCP Documentation

Example Skills:

GitHub: anthropics/skills

Tools:

skill-creator: Built into Claude.ai and Claude Code, generates Skills from descriptions

Getting Support:

Technical questions: Claude Developers Discord community
Bug reports: GitHub Issues (anthropics/skills/issues)

FAQ

Q: What's the difference between Skills and Prompt templates?

A: Prompt templates are one-time use requiring manual paste each time. Skills are persistent knowledge packages that Claude automatically recognizes when and how to use. Skills also support multi-file structures.

Q: How long should SKILL.md be?

A: Keep core instructions under 5,000 words. Put detailed references in references/ directory.

Q: How many Skills can be enabled at once?

A: No hard limit, but 20-50+ simultaneously may slow responses. Group by function and enable as needed.

Original Link: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en