Anthropic’s Complete Guide to Claude Skills Building

--> Anthropic’s Complete Guide to Claude Skills Building - KDnuggets

-->

Join Newsletter

Introduction

Every time you begin a new Claude conversation, you start from zero. Your preferred output format, your team's writing style, your domain vocabulary, and your quality standards are gone. You spend the first few exchanges re-establishing context you already established in the last session and the session before that. For a one-off question, that is fine. For repeatable professional work, it is a tax on every conversation.

Claude Skills are the fix. A skill is a folder of instructions you build once that Claude loads automatically when the task calls for it. Your preferences, workflows, and domain expertise are embedded in the skill, not re-pasted into every chat. Skills launched in October 2025 and quickly became the dominant way to give Claude domain-specific capabilities in Claude Code, Claude Desktop, and the Claude API. Anthropic published the official skills repository at github.com/anthropics/skills as a working reference for how skills should be structured. As of May 2026, the repo has 141,000+ stars and 16,000+ forks, making it one of the most-watched AI tooling repositories on GitHub.

This guide covers the complete picture: what skills are technically, how to plan and design them, the exact file structure and naming rules, how to write instructions that Claude follows reliably, a complete working skill built from scratch, how to test and distribute, and what to do when things go wrong. By the end, you will be able to build a working skill in one sitting, which is exactly what Anthropic's official guide promises for anyone who follows the structure correctly.

What a Skill Actually Is

A skill is a folder. Inside it lives a SKILL.md file (required) and optionally a scripts/ directory for executable code, a references/ directory for documentation Claude loads as needed, and an assets/ directory for templates and supporting files. That is the entire technical definition. Skills are not models, plugins in the WordPress sense, or paid add-ons. They are open-source markdown instructions plus supporting files. You can read every one of them on GitHub before you install anything.

What makes them powerful is the architecture underneath. According to Anthropic's official guide, skills use a three-level progressive disclosure system designed to minimize token usage while maintaining specialized expertise. These levels are:

YAML frontmatter: Always loaded in Claude's system prompt, costing around 100 tokens per skill regardless of how many skills are installed. This metadata layer gives Claude just enough information to decide whether the skill is relevant to the current task without loading the full content.

SKILL.md body: Loaded when Claude determines the skill is relevant. This contains the full instructions, step-by-step workflows, examples, and troubleshooting guidance.

Referenced files: Additional files in references/ and assets/ that Claude navigates only when the task requires it. Long API reference guides, detailed style specs, or extended troubleshooting sections live here rather than in the main file. This system means you can have many skills installed simultaneously without bloating Claude's context; only the frontmatter of each skill loads by default.

Three design principles govern the entire system. Progressive disclosure, as described above. Composability — this means Claude can load multiple skills simultaneously, so your skill should work well alongside others rather than assuming it is the only capability available. Portability — skills work identically across Claude.ai, Claude Code, and the API. Build a skill once, and it runs across all surfaces without modification, as long as the environment supports any dependencies the skill requires.

For teams building on Model Context Protocol (MCP) servers, skills add a knowledge layer on top of connectivity. The way Anthropic frames it in the official guide: MCP provides the professional kitchen — access to tools, ingredients, and equipment. Skills provide the recipes and step-by-step instructions for creating something valuable. MCP tells Claude what it can do. Skills tell Claude how to do it well.

A three-tier pyramid diagram showing progressive disclosure

Planning Your Skill Before You Write a Line

The most common mistake when building a skill is starting with the file structure rather than the use case. Anthropic's guide is explicit: identify two or three concrete use cases before touching any files.

A well-defined use case answers four questions:

What does a user want to accomplish?

What multi-step workflow does this require?

Which tools are needed — Claude's built-in capabilities, or MCP-connected tools?

What domain knowledge or best practices should be embedded that the user would otherwise need to explain every session?

A concrete use case definition looks like this:

Use Case: Blog Post Drafting Trigger: User says "write a blog post", "draft content for our blog", or "create a post following our style guide" Steps:

1. Read the style guide from references/style-guide.md
2. Confirm the topic and target audience with the user
3. Draft following the header structure and tone guidelines
4. Run the quality checklist before delivering the draft

Result: A complete draft that matches the company style guide without the user needing to paste guidelines into the chat

Anthropic's team has observed three categories that cover most skill use cases:

Document and Asset Creation: Creating consistent, high-quality output documents, presentations, frontend designs, and code. The defining characteristic is embedded style guides and quality checklists. Claude's built-in code execution and document creation handle the output with no external tools required. The official Anthropic skills repository contains production-grade skills, including document skills for docx, pdf, pptx, and xlsx manipulation. The frontend-design skill is the canonical example here; it embeds design system tokens and component conventions so every generated UI follows the same standards.

Workflow Automation: Multi-step processes with consistent methodology, research pipelines, content workflows, and onboarding sequences. The key techniques are step-by-step workflows with validation gates between stages, templates for repeating structures, and iterative refinement loops. The skill-creator skill (which ships in the official Anthropic repo and helps you build other skills) is the reference example; it walks users through use case definition, frontmatter generation, and validation as a guided workflow.

MCP Enhancement: Workflow guidance layered on top of a working MCP server. If your users have connected Notion, Linear, or Sentry via MCP but do not know which workflows to run, an MCP enhancement skill provides the knowledge layer — sequencing tool calls, embedding domain expertise, and handling errors. Sentry's code review skill, which automatically analyzes and fixes bugs in GitHub pull requests using Sentry's MCP data, is the reference example from Anthropic's official guide.

Before writing any SKILL.md content, define your success criteria. Anthropic recommends two types. Quantitative: the skill triggers on at least 90% of relevant queries, completes the workflow in a defined number of tool calls, and produces zero failed API calls per run. Qualitative: users do not need to redirect Claude mid-workflow, outputs are structurally consistent across repeated runs, and a new user can accomplish the task on the first try without guidance. These are rough benchmarks rather than hard thresholds, but defining them upfront gives you something concrete to test against.

The Technical Requirements

This is where most skills fail silently. The rules are strict, and the errors they produce are confusing because Claude simply will not load a skill that violates them — with no error message to explain why.

// File Structure

your-skill-name/ ├── SKILL.md # Required -- main skill file ├── scripts/ # Optional -- executable code │ ├── process_data.py │ └── validate.sh ├── references/ # Optional -- documentation loaded as needed │ ├── api-guide.md │ └── examples/ └── assets/ # Optional -- templates, fonts, icons └── report-template.md

// Critical Naming Rules

SKILL.md is case-sensitive. The file must be named exactly SKILL.md. Variations like skill.md, SKILL.MD, or Skill.md will not be recognized. Claude simply will not load the skill — no error, no warning.

Folder names must use kebab-case. Lowercase letters and hyphens only. No spaces (Notion Project Setup), no underscores (notion_project_setup), no capitals (NotionProjectSetup). The folder name should match the name field in your frontmatter exactly.

No README.md inside the skill folder. All documentation for Claude goes in SKILL.md or references/. If you are distributing on GitHub, put your human-readable README at the repository root, not inside the skill folder itself.

Reserved names: skill names cannot contain "claude" or "anthropic"; these are reserved by Anthropic and will be rejected.

No XML angle brackets in frontmatter. Frontmatter appears directly in Claude's system prompt. XML-like content could inject unintended instructions, so this is a security restriction enforced at the platform level.

// YAML Frontmatter

The frontmatter is how Claude decides whether to load your skill. If it is weak or missing trigger conditions, the skill will not activate reliably. This is the single most common failure mode.

Minimal required format:

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

The name field must be kebab-case and match the folder name exactly.

The description field must include both what the skill does and when to use it. The character limit is 1024. According to Anthropic's engineering guidance, this field provides just enough information for Claude to know when each skill should be used without loading all of it into context. Descriptions without trigger conditions are the primary reason skills fail to load when they should.

Full format with all optional fields:

--- name: your-skill-name description: What it does and when to use it. (Under 1024 characters, no XML tags.) license: MIT compatibility: Requires Claude Code with Python 3.9+ in the environment. metadata: author: Your Name version: 1.0.0 mcp-server: your-service-name ---

license matters if you are making the skill open source.

compatibility (1–500 characters) describes environment requirements; if the skill needs specific system packages, network access, or a particular product surface, document it here.

metadata accepts any custom key-value pairs; author, version, and mcp-server are the most commonly used.

Writing Skills That Actually Work

// The Description Field Formula

The structure that consistently produces reliable triggering: [What it does] + [When to use it] + [Key capabilities]. Anthropic's guide provides clear examples of both good and bad descriptions:

Good -- specific task, specific trigger phrases, file type mentioned

description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

Good -- named service, concrete trigger language

description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

Good -- end-to-end workflow, specific trigger phrases

description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up

[truncated for AI cost control]