Learn

Skills

Skills are SKILL.md files that teach Claude repeatable workflows. They extend Claude with domain expertise for specific tasks, from generating meeting notes to orchestrating multi-service deployments.

What Skills Are

A skill is a folder containing a SKILL.md file (and optional scripts, references, assets) that gives Claude specialized knowledge. Skills use progressive disclosure to minimize token usage:

Level 1: YAML Frontmatter    → Always in system prompt (routing metadata)
Level 2: SKILL.md Body        → Loaded when skill matches user intent
Level 3: Linked Files         → Loaded on demand (references/, scripts/, assets/)

This matters because Claude has limited context. Loading 20 skills’ full instructions would waste tokens. Instead, Claude sees 20 short descriptions, picks the right one, then loads its full instructions.

Folder Structure

your-skill-name/           # kebab-case, no spaces/capitals
├── SKILL.md               # Required - exactly this name (case-sensitive)
├── scripts/               # Optional - executable code (Python, Bash)
├── references/            # Optional - docs loaded on demand
└── assets/                # Optional - templates, fonts, icons

Rules:

  • Folder name = kebab-case (my-cool-skill, not My Cool Skill or my_cool_skill)
  • No README.md inside the skill folder (all docs go in SKILL.md or references/)
  • Names can’t include “claude” or “anthropic” (reserved)

The Frontmatter Contract

The YAML frontmatter determines when Claude activates a skill:

---
name: sprint-planner
description: >
  Manages Linear sprint planning.
  Use when user says "plan sprint",
  "create sprint tasks", or
  "sprint planning".
license: MIT
compatibility: Requires Linear MCP
metadata:
  author: Your Name
  version: 1.0.0
  mcp-server: linear
---

Description Formula

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

Good descriptions include trigger phrases - the actual words users say. Claude pattern-matches against these to decide which skill to load.

# Good - specific triggers, clear scope
description: >
  Analyzes Figma design files and generates developer handoff docs.
  Use when user uploads .fig files, asks for "design specs",
  "component documentation", or "design-to-code handoff".

# Bad - vague, no triggers
description: Helps with projects.

Security Restrictions

  • No XML angle brackets (< >) anywhere in frontmatter
  • No code execution in YAML (safe parsing only)
  • Description max 1024 characters
  • Compatibility max 500 characters

Three Categories

1. Document and Asset Creation

Consistent, high-quality output (docs, presentations, code, designs).

Key techniques: Embedded style guides, template structures, quality checklists. No external tools needed - uses Claude’s built-in capabilities.

When to choose: You have a repeatable output format and want consistency across sessions.

2. Workflow Automation

Multi-step processes that benefit from consistent methodology.

Key techniques: Step-by-step workflow with validation gates, templates, built-in review suggestions, iterative refinement loops.

When to choose: You find yourself explaining the same multi-step process repeatedly.

3. MCP Enhancement

Workflow guidance layered on top of MCP tool access.

Key techniques: Coordinates multiple MCP calls in sequence, embeds domain expertise about the service, provides context users would otherwise need to specify.

When to choose: You have an MCP server and users don’t know the optimal workflow.

MCP = Professional kitchen (tools, ingredients, equipment)
Skills = Recipes (step-by-step instructions for creating value)
Together = Users accomplish complex tasks without figuring out every step

Open Standard

Skills were published as an open standard in December 2025. The same SKILL.md format works across:

  • Claude Code
  • Cursor
  • Gemini CLI
  • Codex CLI
  • Antigravity IDE

Organization-level skills (workspace-wide deployment, centralized management) shipped in January 2026.

Design Principles

Composability - Your skill may run alongside others. Write instructions that work independently.

Portability - Same skill works on Claude.ai, Claude Code, and API. Avoid surface-specific assumptions unless noted in compatibility.

Self-containment - The best skills are fully self-contained in SKILL.md. Scripts and references are for heavy lifting (validation scripts, large API docs), not for splitting simple instructions across files.

Next