Learn how to package instructions into skills that teach Claude specific tasks and workflows. Discover the structural requirements, MCP integration patterns, and best practices for creating powerful, reusable agent workflows.
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. Instead of re-explaining your preferences, processes, and domain expertise in every conversation, skills let you teach Claude once and benefit every time.
MCP (Model Context Protocol) provides the professional kitchen: Access to tools, ingredients, and equipment (e.g., Notion, Asana, Linear databases - "What Claude can do").
Skills provide the recipes: Step-by-step instructions on how to create something valuable ("How Claude should do it"). Without skills, users connect an MCP but don't know what to do next. With skills, pre-built workflows activate automatically when needed, with consistent results and embedded best practices.
Skills use a three-level system to minimize token usage while maintaining expertise:
First Level (YAML frontmatter): Always loaded in Claude's system prompt to know WHEN a skill should be used.
Second Level (SKILL.md body): Loaded only when Claude thinks the skill is relevant.
Third Level (Linked files): Folders/files bundled in the directory that Claude explores as needed.
Claude can load multiple skills simultaneously. Your skill should work well alongside others and not assume it is the only capability available. Design modular workflows that interoperate.
Skills work identically across Claude.ai, Claude Code, and API. Create a skill once and it works across all surfaces provided the environment supports its dependencies.
Skill folders must be named correctly and contain a `SKILL.md` file. Including a `README.md` inside your skill folder is an anti-pattern (it goes in the repository root, not the skill folder).
your-skill-name/
├── SKILL.md # Required - main skill file (exact case)
├── scripts/ # Optional - executable code
│ └── process_data.py
├── references/ # Optional - documentation
│ └── api-guide.md
└── assets/ # Optional - templates, etc.
└── report-template.md SKILL.md grading is strictly case-sensitive. No variants (SKILL.MD, skill.md) are accepted.notion-project-setup (No capital letters, underscores, or spaces).< >) or the words "claude" or "anthropic" in the YAML frontmatter due to security restrictions.The YAML frontmatter is the most important part of a skill because it decides if the skill loads. It sits at the absolute top of the SKILL.md.
---
name: notion-project-setup
description: End-to-end customer onboarding workflow. Handles account creation, payment setup. Use when user says "onboard new customer", "set up subscription", or "create account".
compatibility: ProjectHub 1.0.0
---The description MUST include both what the skill does AND when to use it (trigger conditions/phrases). It must be under 1024 characters.
Domain 1 focuses heavily on patterns for execution. When designing a skill, consider whether you are creating a "Sequence" or an "Iteration".
Explicit step ordering where dependencies flow from Step A to B to C. Example: Onboard -> Step 1: Create Account -> Step 2: Set up Payment -> Step 3: Create Subscription -> Step 4: Email.
Output quality improves with continuous loops. Example: Report Generation -> Initial Draft -> Run Validation Script -> Fix Issues -> Regenerate -> Repeat -> Finalize.
Workflows spanning multiple services. Example: Design Export (Figma) -> Asset Storage (Drive) -> Task Creation (Linear) -> Notification (Slack). Requires data passing and validation between MCPs.
Taking the same abstract action but routing to different tools based on context. Example: File > 10MB -> Cloud Storage. File is code -> GitHub. Decision trees must be explicitly laid out in instructions.