Anthropic’s Secret 33‑Page Guide: Build Claude Skills from File Structure to Deployment

Anthropic has quietly published a 33‑page PDF guide that serves as the definitive manual for building Claude Skills, a standardized capability‑packaging mechanism introduced at the end of 2025. The guide is hosted on Anthropic’s resources page and targets developers and advanced users.

A Skill is simply a folder. It must contain a SKILL.md file (the "brain") and may optionally include scripts/, references/, and assets/. The crucial part is a short YAML preamble inside SKILL.md that tells Claude whether to activate the skill.

The guide describes Anthropic’s three‑layer progressive disclosure design: Layer 1 – the YAML preamble lives in the system prompt so Claude knows the skill exists; Layer 2 – the full SKILL.md loads only when the skill is triggered; Layer 3 – associated files are discovered on demand. This approach saves tokens and lets dozens of skills coexist without overloading the context.

The description field in the YAML is highlighted as the most important metadata. It should follow the pattern "[What] + [When to use] + [Key capability]" and include user‑facing trigger phrases. The guide shows bad examples such as Helps with projects. (too vague) and good examples like:

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".

Five core work modes are outlined:

Sequential workflow : multi‑step processes with fixed order and validation gates (e.g., new‑customer onboarding, code review).

Multi‑MCP coordination : orchestrates several MCP services such as Figma → Drive → Linear → Slack.

Iterative optimization : generate a draft, run a script to check quality, refine, and repeat until a quality threshold is met.

Context‑aware selection : dynamically pick tools based on conditions (file size, document type, code repository).

Domain‑specific intelligence : embed industry knowledge, e.g., financial compliance checks before payment processing.

The relationship between Skill and MCP is clarified with a kitchen metaphor: MCP provides the kitchen (tools, ingredients, equipment) while the Skill provides the recipe (how to combine them). Without a Skill, MCP users lack guidance on what to do next, must repeat explanations, and see inconsistent results.

Testing is divided into three layers: Trigger tests (explicit trigger phrase, synonym trigger, and ensuring unrelated topics do not fire); Functional tests (verify output, API success, edge‑case handling); Performance comparison (the guide reports that a task with a Skill consumes ~6,000 tokens versus ~12,000 tokens without, and requires only 2 confirmation turns instead of 15). A quick debugging tip is to ask Claude “When would you use [skill name]?” to have it echo the description.

Distribution steps recommended by the guide are:

Publish the skill folder in a public GitHub repository.

Add installation instructions to the MCP documentation.

Explain the value of the "MCP + Skill" combination.

Installation can be done by uploading a zip file to Claude.ai Settings → Capabilities → Skills, or by placing the folder directly into the Claude Code skills directory.

Skills are positioned as an open standard; several third‑party tools (Asana, Atlassian, Canva, Figma, Sentry, Zapier) already have official Skills. Anthropic also offers a skill‑creator tool that can produce a first usable skill in 15–30 minutes, making now an ideal time to join the ecosystem.