How to Create Claude Skills: Complete Guide (2026)

1. What Are Claude Skills? (And How They Differ From Prompts)

Before you build anything, it helps to understand exactly what a Skill is at a technical level, how it differs from a prompt, and where it fits inside the broader Anthropic Claude ecosystem. This section builds the conceptual foundation everything else rests on.

Defining Claude Skills

A Claude Skill is a self-contained, named, versioned unit of instruction that Claude can invoke on demand. In practical terms, it is a folder. At its simplest, a skill is a directory that contains a SKILL.md file, and this file must start with YAML frontmatter that contains some required metadata: name and description.

That folder is the whole thing. There is no separate model, no proprietary binary, no paid add-on. Skills are not models, plugins in the WordPress sense, or paid add-ons. They are open-source markdown instructions plus supporting files. This is worth internalising early, because it changes how you think about the work. You are not programming a system. You are writing documentation so clear and so well-scoped that Claude can follow it perfectly every time.

Skills surface in two main places. In the Claude API, you can use Anthropic's pre-built skills, and upload custom skills, via the Claude API, and skills are simple to create, just a folder with a SKILL.md file containing YAML frontmatter and instructions. In Claude Code, they live in a directory in your project or plugin. You create a skills directory in your plugin or project root and add skill folders containing SKILL.md files, and Claude discovers and uses them automatically when the plugin is installed.

There is also a public registry of examples. Anthropic maintains an open repository of Skills that demonstrate the range of what is possible. This repository contains skills that demonstrate what is possible with Claude's skills system, ranging from creative applications like art, music, and design to technical tasks like testing web apps and MCP server generation to enterprise workflows. These are a valuable reference when you start building your own.

The best mental model: if prompts are sticky notes you scribble and throw away, Skills are documented Standard Operating Procedures. A sticky note reminds one person once. An SOP standardises how everyone does a task, forever, with a clear owner and a version number.

A few pieces of vocabulary to fix in your mind now, because they recur throughout this guide:

• SKILL.md: the required file at the heart of every Skill. Note the uppercase filename in Anthropic's implementation, though people often refer to the "skill.md file" generically.
• Frontmatter: the YAML block at the top of the file holding metadata like name and description.
• Skill body: the Markdown instructions below the frontmatter.
• Skill builder: the authoring workflow, whether a template, the API, or a directory in Claude Code.
• Invocation: the moment Claude decides a Skill is relevant and loads it.
• Skill scope: how narrow or broad the Skill's purpose is.

Running Claude across multiple repos all week to test your Skill library? That is often a Max 20x plan at $200/month, billed in USD. With Bleap you pay at the real exchange rate, 0% FX fees, and earn a flat 20% cashback on Claude, ChatGPT, and Gemini renewals, no card subscription required. Get the Bleap card →

Claude Prompts vs Skills: The Critical Differences

People often ask why they cannot just keep using a good prompt. Sometimes you should. But once a task is repeated, shared, or business-critical, a Skill wins on almost every dimension. Here is the breakdown.

Persistence. A prompt exists only inside the conversation turn where it is pasted. Once the session ends, it is gone. A Skill persists across sessions and users. It is stored, indexed, and available whenever it is relevant.

Discoverability. This is the subtle one. Claude cannot see a prompt until someone injects it. A Skill, by contrast, advertises itself. At startup, the agent pre-loads the name and description of every installed skill into its system prompt, providing just enough information for Claude to know when each skill should be used without loading all of it into context. Claude actively decides when to reach for a Skill. It can never decide to reach for a prompt it has never seen.

Reusability. A Skill can be called by any authorised user or subagent without anyone copying and pasting text. A prompt has to be manually shared and re-shared, and it drifts every time.

Versioning. Skills can be iterated and tracked over time. Raw prompts sitting in user messages cannot be versioned in any meaningful way.

Tool integration. Skills can bundle scripts and reference material and describe exactly how and when to use them. Prompts cannot natively carry that structure.

Composability. Skills can reference other resources and be wired into subagents for delegated work. Prompts are monolithic blocks of text.

Here is a side-by-side comparison across eight dimensions:

When to use a prompt vs when to build a Skill. The decision framework is simple. Use a prompt for one-off, exploratory, or highly context-specific requests. Build a Skill when a task is repeated regularly, needs to produce consistent output, will be used by more than one person, or encodes knowledge that would otherwise have to be re-explained every session. If you find yourself pasting the same instructions twice, that is your signal.

Where Skills Fit in the Anthropic Claude Ecosystem

Skills do not exist in isolation. Understanding how they relate to the rest of the Claude ecosystem stops you from building a Skill for something another mechanism handles better.

Skills vs Projects. In Claude.ai, Projects group conversations and files around a shared goal. Skills enhance Projects by adding reusable procedural knowledge, but they are not the same thing. A Project is a workspace. A Skill is a capability you can invoke inside that workspace or anywhere else.

Skills vs MCP. This distinction matters a lot. The Model Context Protocol is the connectivity layer, the way Claude reaches external tools, data sources, and services. Skills are the instruction layer, telling Claude how and when to act. You often use both together: MCP connects Claude to your database, and a Skill tells Claude the exact procedure for querying and formatting that data. One of Anthropic's example Skills even covers MCP server generation, showing how tightly the two concepts interlock.

Skills vs subagents. Skills can be wired into custom subagents so a specialised agent handles a delegated task in isolation. You can share skills with your team by committing them to a repository, distribute them through plugins, deploy them organization-wide, and wire Skills into custom subagents for isolated, expert task delegation. The Skill carries the expertise; the subagent provides the isolated execution context.

Skills vs the API. Skills are not locked to the chat UI. They are accessible programmatically, which is what makes them viable for production automation, CI pipelines, and embedded product features.

Skills vs the context hierarchy. When Claude responds, it weighs the system prompt, the Skill content it has loaded, the user's messages, and any tool results. Skills sit above the individual message but below the immovable system-level guardrails. Knowing this hierarchy helps you write Skills that guide behaviour without fighting Claude's defaults.

Why Claude Skills Are a Game-Changer for AI Automation

The strategic value of Skills compounds. Here is where the leverage comes from.

Eliminating prompt drift. When a team relies on a shared Skill, everyone invokes the same authoritative instructions. There is no more "which version of the prompt are you using?" The Skill is the source of truth.

Widening access. A well-built Skill lets non-technical stakeholders benefit from sophisticated automation. They do not need to know how to write a 400-word system prompt. They just describe what they want, and Claude reaches for the right Skill.

Reducing context window waste. This is the technical genius of the design. Skills use a three-level loading system to manage context efficiently, and this progressive disclosure allows you to install many different skills to perform complex tasks without bloating your context window. Static instructions live outside the conversation until the moment they are needed.

The compounding library effect. Each Skill you build makes the next one more valuable, because Skills can reference shared resources and combine into workflows. A team with 40 well-scoped Skills has a genuinely different capability profile than a team pasting prompts. One team running dozens of Skills reported that the overhead is roughly 1,500 tokens total for all 40 skills, with only the relevant one expanding when needed.

Real-world use cases. The pattern shows up everywhere: code review automation, customer support playbooks, data normalisation, content QA, brand-compliant document generation, and research synthesis. The power of skills lies in their ability to encode institutional knowledge, standardize outputs, and handle complex multi-step workflows that would otherwise require repeated explanation or investment in building a custom agent.

The productivity thesis is straightforward. Any time a knowledge worker spends re-explaining the same context to an AI is time wasted, and it is time that scales badly across a team. Structured, reusable workflows remove that waste. The exact savings depend on your workflows, so treat any specific percentage claims you see online with healthy skepticism, but the direction is clear: less repetition, more consistency, more leverage.

2. How Claude Skills Work: Architecture, Content Lifecycle, and Skill Types

Now that you know what Skills are and why they matter, let us open the hood. Understanding the architecture and lifecycle is what separates people who write Skills that trigger reliably from people who write Skills that sit unused because Claude never realises they are relevant.

The Claude Skill Architecture at a Glance

At a high level, the flow looks like this: a user or agent makes a request, Claude checks the metadata of every installed Skill, decides whether one is relevant, loads that Skill's full content into context if so, and then generates a response enriched by that content. You can picture it as User or Agent → Skill metadata scan → relevance decision → content load → enriched response.

Every Skill has three conceptual layers:

• Definition. What the Skill is: its name, description, version, and metadata. This is what Claude sees at all times.
• Content. What the Skill delivers into context: the full instructions, examples, and any referenced resources. This loads only when needed.
• Execution. How Claude actually uses the loaded content to complete the task, including any scripts or tools the Skill points to.

Where are Skills stored? It depends on your setup. In Claude Code they live in a skills/ directory in your project or plugin. Via the API they are uploaded to Anthropic-managed storage. Teams commonly keep the canonical versions in their own Git repository and distribute from there.

How does Claude "know" a Skill exists? Through the always-loaded metadata layer. The YAML frontmatter is always loaded in Claude's system prompt, costing around 100 tokens per skill regardless of how many skills are installed, and this metadata layer gives Claude just enough information to decide whether the skill is relevant to the current task without loading the full content. That 100-token cost is the price of admission for a Skill to be discoverable, and it is why the design scales to dozens of Skills.

Finally, there are two ways a Skill gets invoked. Implicit invocation is when Claude itself decides a Skill is relevant based on the description and the user's request. Explicit invocation is when a user or agent names the Skill directly. Both are valid; the balance between them is something you design for when you write the description.

The Skill Content Lifecycle

A Skill moves through a predictable lifecycle from idea to production and beyond. Understanding each stage, and its failure modes, saves you hours of debugging.

Stage 1, Authoring. You write the SKILL.md and any supporting files. This is where most of the quality is won or lost. Pitfall: writing before you have clearly defined the problem. Before writing anything, clarify what problem your skill solves, because strong skills address concrete needs with measurable outcomes.

Stage 2, Publishing. You commit the Skill to wherever Claude will read it: a directory, the API, or a CI/CD pipeline. Pitfall: publishing to the wrong location or forgetting to install the plugin, so Claude never discovers it.

Stage 3, Indexing. Claude loads the Skill's metadata into the system prompt at startup. Pitfall: expecting a newly added Skill to be available mid-session without a restart or reload.

Stage 4, Invocation. Claude matches a request against the Skill description and decides to use it. Pitfall: the description is too narrow, so Claude never triggers the Skill.

Stage 5, Injection. The full SKILL.md body loads into context. The actual body of the file is the second level of detail, and if Claude thinks the skill is relevant to the current task, it will load the skill by reading its full SKILL.md into context. Pitfall: an oversized body that eats context and buries the important instructions.

Stage 6, Execution. Claude processes the enriched context and produces its response, running any scripts the Skill points to. Pitfall: instructions that conflict with Claude's defaults, producing inconsistent output.

Stage 7, Iteration. You version, edit, and re-publish. Pitfall: changing a Skill without bumping the version, so nobody knows which behaviour they are getting.

The single most useful habit here is to test triggering and execution as separate concerns. Test triggering and execution separately: if skills do not activate, broaden your description and add use cases, and if results are inconsistent, add specificity to instructions and include validation steps. Those are two different problems with two different fixes, and treating them as one is why people go in circles.

Types of Skill Content

Not every Skill does the same job. Recognising the type you are building shapes how you structure the SKILL.md.

Instruction-only Skills deliver a set of behavioural rules or a step-by-step procedure. A code review checklist is the classic example: no external data, no tools, just a reliable process Claude follows every time.

Context-enrichment Skills inject domain knowledge, reference data, or terminology. Think of a Skill that carries your company's glossary, product taxonomy, or brand voice so Claude speaks the right language without you re-explaining it.

Tool-activation Skills describe how and when to use specific tools or scripts. These often pair with MCP connections and point Claude at executable helpers in the scripts/ directory.

Template Skills deliver structured output formats: a JSON schema, a report template, a code scaffold. The value is consistency of shape, not just content.

Hybrid Skills combine several of the above in one unit. Anthropic's own document-editing Skills are a good illustration. One of the skills that powers Claude's document editing abilities addresses the fact that Claude already knows a lot about understanding PDFs but is limited in its ability to manipulate them directly, such as filling out a form, and this PDF skill gives Claude these new abilities. That blends instructions, tools, and templates.

Choosing the right type. Ask what the task actually needs. Pure behaviour change? Instruction-only. Missing knowledge? Context-enrichment. Needs to do something external? Tool-activation. Needs a specific output shape? Template. Several of these at once? Hybrid, but keep it as focused as you can.

How type affects structure. Instruction-only and template Skills are usually short and can live entirely in the SKILL.md body. Context-enrichment and hybrid Skills often need supporting files, which is exactly what the progressive disclosure system is designed for. As a rule of thumb, keep the SKILL.md body to essentials and under 500 lines, and if approaching this limit, split content into separate files.

How Claude Decides to Invoke a Skill

This is the part people most often get wrong, so it deserves care. Invocation is driven primarily by the description field. Claude reads the description of every installed Skill and semantically matches it against the current request. Get the description right and the Skill fires reliably. Get it wrong and even a brilliant Skill sits idle.

There is a known behavioural quirk to design around. Claude has a tendency to undertrigger skills, to not use them when they would be useful, and to combat this you should make the skill descriptions a little bit pushy. Anthropic's own guidance is to spell out the situations that should activate the Skill, even the implicit ones. For example, rather than a bare one-liner, you might add "make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they do not explicitly ask for a dashboard."

Explicit invocation works through direct reference: a user or agent names the Skill, or a slash command triggers it. This is the most reliable path but relies on the caller knowing the Skill exists.

Trigger phrases and examples. Including example utterances and use cases in your description sharpens the semantic match. These give Claude concrete signals of when relevance applies. Anthropic's advice when a Skill will not fire is direct: if skills do not activate, broaden your description and add use cases.

Confidence and over-triggering. The opposite failure is a description so broad the Skill fires on nearly everything, hijacking unrelated conversations. The fix is scope. A tightly scoped description with specific trigger conditions triggers when it should and stays quiet when it should not.

Multiple Skills and prioritisation. When several Skills could match, Claude weighs relevance. Priority conflicts are a real troubleshooting category, and part of good Skill design is making sure two Skills do not compete for the same territory with overlapping descriptions.

Dynamic context. Runtime variables, the specific files open, the tools connected, the phrasing of the request, all influence which Skill activates. A Skill that references a database will more readily activate when a database connection is present. Designing for this dynamic context is what makes a Skill feel like it "just knows" when to help.

Building and testing Skills all day means burning through your Claude plan. Claude Pro is $20/month and Max runs $100 to $200/month, billed in USD. Pay with Bleap and you get 0% FX fees plus a flat 20% cashback on Claude, ChatGPT, and Gemini, with no card subscription. Get the Bleap card →

3. Creating Your First Claude Skill: A Step-by-Step Walkthrough

Enough theory. Let us build a working Skill end to end. We will use a real example, a Code Review Checklist Skill, and walk through every step from setup to a successful first invocation.

Prerequisites and Environment Setup

First, confirm you have access. Skill creation is available through Claude Code, the Claude API, and Claude.ai, with organisation-wide management still maturing. As of the current guidance, in Claude.ai skills are currently individual to each user, though org-wide management and sharing capabilities are coming soon, and in the meantime it is suggested to create a shared document repository with skill specifications to prepare for upcoming features while establishing good governance today.

For paid access, the relevant Claude plans are straightforward. Claude pricing in 2026 spans seven tiers: Free ($0), Pro ($20/month), Claude Max 5x ($100/month), Max 20x ($200/month), Team Standard ($25/seat/month), Team Premium ($125/seat/month), and Enterprise (custom). If you are building Skills as part of a team workflow, the Team and Enterprise plans add the admin controls you will eventually want. If you are automating programmatically, the API is billed separately per token.

Required knowledge. Honestly, not much. Basic Markdown and a clear understanding of the task you want to automate. That is the bar.

Recommended tools. VS Code with a Markdown preview extension makes authoring SKILL.md far more pleasant. Git gives you version control from day one. Keep a dedicated Claude conversation open purely for testing, separate from your real work, so context does not contaminate your tests.

Local development folder. Set up a folder before you publish anything, so your Skills have a clean home and a version history.

Three ways to create a Skill. You can author directly in a skills/ directory in Claude Code, upload via the Claude API, or start from Anthropic's template. You can create skills that transform Claude from general-purpose assistant into specialized expert either with the skill creator template or manually, and to make it easy it is recommended to build your SKILL.md file with the template and tailor from there.

Planning Your Skill Before You Write a Single Line

Resist the urge to open your editor. The best Skills are planned first. Anthropic's guide is explicit: identify two or three concrete use cases before touching any files, and ask what domain knowledge or best practices should be embedded that the user would otherwise need to explain every session.

Answer these five questions before authoring:

1. What specific task does this Skill enable? For our example: "Review a code diff against our team's quality checklist and produce a structured findings report."
2. How will Claude or a user know when to invoke it? When someone shares a diff, pull request, or asks for a code review.
3. What information must be in context for the Skill to work? The checklist criteria and the output format. The code itself comes from the user.
4. What tools, if any, does the Skill need? For a pure checklist, none. If it ran linters, it would need script access.
5. Who should have access? Start private, expand to the team once it is proven.

Scope narrow, not broad. A Skill that "helps with code" is useless because it triggers on everything and delivers nothing specific. A Skill that "reviews Python pull requests against our team's checklist and outputs findings grouped by severity" is precise, triggers correctly, and delivers consistent value. Narrower almost always wins.

Write the description first, as a spec. Treat the description like a specification document. If you cannot describe in two or three sentences exactly what the Skill does and when it should fire, you are not ready to write the body.

Identify the minimum viable Skill. Start with the smallest version that delivers value, ship it, and iterate. Anthropic frames the goal clearly: by the end you will be able to build a working skill in one sitting, which is exactly what the official guide promises for anyone who follows the structure correctly.

Step 1: Set Up Your Skill Directory

Create a folder for the Skill. The recommended structure:

code-review-checklist/
├── SKILL.md ← required
├── references/ ← optional supporting knowledge
├── scripts/ ← optional executable helpers
└── assets/ ← optional static files

This mirrors Anthropic's own convention. Inside the skill folder 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.

Naming conventions. Use kebab-case for folder names (code-review-checklist, not CodeReviewChecklist). Prefix by category so a large library stays navigable: qa-, dev-, ops-, content-. Our example might live as dev-code-review-checklist.

One directory per Skill. Keeping each Skill self-contained is not just tidiness. It means you can version, share, and move Skills independently, which pays enormous dividends once you have dozens of them. Each skill is self-contained in its own folder with a SKILL.md file containing the instructions and metadata that Claude uses.

Version control. Initialise Git in the folder or its parent, and use Git tags for Skill versions. When you bump a Skill from 1.2.0 to 1.3.0, tag it. Your future self, debugging why behaviour changed last Tuesday, will be grateful.

Step 2: Write the SKILL.md File (Minimum Viable Version)

Here is a complete, working SKILL.md for our Code Review Checklist Skill. This is the whole file, frontmatter to body.

---
name: code-review-checklist
description: >
Reviews code diffs and pull requests against the team's quality
checklist and returns findings grouped by severity. Use this skill
whenever the user shares a diff, a pull request, a code snippet for
review, or asks for a code review, quality check, or PR feedback,
even if they do not explicitly say "checklist."
version: 1.0.0
---

# Code Review Checklist

You are performing a structured code review. Work through every
item in the checklist below against the code the user provides.

## Checklist

1. **Correctness**, Does the code do what it claims? Flag logic errors.
2. **Null and error handling**, Are edge cases and failures handled?
3. **Security**, Flag hardcoded secrets, unsafe input handling, or
injection risks.
4. **Tests**, Is there adequate test coverage for the change?
5. **Naming and style**, Do names follow our conventions
(kebab-case files, camelCase variables)?
6. **Readability**, Could a new teammate understand this in 60 seconds?

## Output format

Group findings under three headings: **Blocking**, **Should fix**, and
**Nice to have**. For each finding, cite the relevant line or function
and give a one-line, actionable recommendation. End with a one-sentence
overall verdict.

## Guidelines

- If the code is clean, say so plainly. Do not invent issues.
- Be specific. "Improve error handling" is useless;
"wrap the file read in a try/except" is useful.
- Do not rewrite the whole file unless asked. Point to the fix.

This structure follows Anthropic's template closely. The public template shows the same skeleton: a name and a clear description of what the skill does and when to use it, a heading with instructions Claude will follow when the skill is active, an Examples section, and a Guidelines section.

Let us annotate what matters:

• The description is doing the heavy lifting. Notice it is deliberately "pushy," listing the situations that should trigger it and explicitly covering the case where the user does not use the word "checklist." That combats undertriggering.
• The body is a clear procedure, not a vague suggestion. The checklist items are concrete and each one is actionable.
• The output format is fixed. This is what turns "some feedback" into a consistent, comparable report every time.
• The guidelines close loopholes, telling Claude not to fabricate problems and not to over-rewrite.

Common first-draft mistakes. Descriptions that are too terse. Instructions that conflict with Claude's defaults (for example, telling it to be terse and then asking for detailed explanations). Bodies that balloon past the point of usefulness. And output formats left implicit, which produces inconsistent results.

The read-it-aloud test. Read your SKILL.md out loud. If a sentence sounds tangled or ambiguous to you, it will confuse Claude too. Clear writing is not a nicety here; it is the entire engineering task.

Step 3: Publish the Skill

How you publish depends on your environment.

In Claude Code, drop the folder into your project's skills/ directory and Claude picks it up. You create a skills directory in your plugin or project root and add skill folders containing SKILL.md files, and Claude discovers and uses them automatically when the plugin is installed.

Via the API, upload the Skill folder using the Skills API. Anthropic's documentation includes a Skills API Quickstart for exactly this.

In Claude.ai, add the Skill through the Skills interface in your workspace, paste or upload the SKILL.md, and set the initial access level. Remember that in Claude.ai today, Skills are scoped to the individual user, with broader sharing on the roadmap.

Setting access level. Start private. Prove the Skill works in isolation before you expose it to a team or workspace. It is far easier to widen access later than to unwind a broken Skill that a dozen people are already relying on.

After you publish, there is a brief indexing step where the metadata loads into the system prompt. In a running session, you may need to reload or start fresh for a newly added Skill to become available.

Step 4: Run Your First Invocation Test

Open a fresh conversation. This matters. An existing conversation carries context that can mask whether your Skill actually fired or whether Claude is just responding to earlier messages.

Test implicit invocation first. Paste a code diff and simply say, "Can you review this?" Do not mention the Skill by name. If your description is good, Claude should reach for the Skill automatically and return output in your defined format.

Then test explicit invocation. Reference the Skill directly and confirm it fires on demand.

Interpret the response. The clearest signal the Skill loaded is that the output matches your defined format exactly: findings grouped under Blocking, Should fix, and Nice to have, with a one-sentence verdict. If you get generic prose feedback instead, the Skill probably did not trigger.

Five indicators your Skill is working:

1. The output follows your specified format precisely.
2. Claude applies your specific checklist items, not just generic best practices.
3. It respects your guidelines (does not fabricate issues on clean code).
4. It triggers on natural requests without you naming it.
5. Behaviour is consistent across repeated tests with different inputs.

If triggering is unreliable, remember the separation-of-concerns rule: fix triggering by broadening and sharpening the description; fix output quality by adding specificity and validation steps to the body.

Common Beginner Mistakes and How to Fix Them

A handful of mistakes account for most early frustration.

Instructions that fight Claude's defaults. If your Skill tells Claude to behave in a way that contradicts its baseline behaviour without clear reasoning, you get inconsistent results. Fix: be explicit about why the deviation is needed, and validate.

Descriptions so broad the Skill triggers on everything. A Skill that fires on every message is worse than useless. Fix: narrow the scope, add specific trigger conditions.

Wrong access level before sharing. Publishing team-wide before testing, or leaving a broken Skill exposed. Fix: private first, widen only after validation.

Over-stuffed bodies. A bloated SKILL.md wastes context and buries the key instructions. Fix: keep the body under 500 lines and push supporting detail into references/. As the guidance goes, keep SKILL.md body to essentials and under 500 lines, and if approaching this limit, split content into separate files.

Not testing edge cases. A Skill that works on the happy path but breaks on unusual input will erode trust fast. Fix: build a proper test-case library. Create a test case library covering normal usage, edge cases, and out-of-scope requests.

4. Structuring the SKILL.md File: Metadata, Frontmatter, and Body

You have built a working Skill. Now let us go deep on the file itself, because mastering SKILL.md structure is what takes you from Skills that mostly work to Skills that work every time, at scale, across a team.

Understanding the SKILL.md File Format

Why Markdown? Because it is human-readable, diff-friendly in Git, universally supported, and forces clarity. Markdown is also how Claude already "thinks" about structured text, so instructions in Markdown are instructions Claude follows naturally. The choice is deliberate: Skills are meant to be written and reviewed by humans as much as executed by Claude.

The two-part structure. Every SKILL.md is a YAML frontmatter block followed by a Markdown body. A SKILL.md file must begin with YAML frontmatter that contains a file name and description, which is loaded into its system prompt at startup. The frontmatter is metadata; the body is instruction.

How the two parts are treated differently. This is the crux of the progressive disclosure architecture. The frontmatter is always loaded. The body loads only when relevant. The YAML frontmatter is always loaded in Claude's system prompt, costing around 100 tokens per skill, giving Claude just enough to decide relevance without loading the full content; the SKILL.md body is loaded when Claude determines the skill is relevant, and it contains the full instructions, step-by-step workflows, examples, and troubleshooting guidance.

File size limits. There is no hard-and-fast universal number, but the practical guidance is a body under 500 lines. Exceed that and you should split content into references/ files that Claude loads on demand. Anthropic designed a third disclosure level for exactly this: when a Skill grows too large for a single SKILL.md, supporting files carry the overflow. As skills grow in complexity, they may contain too much context to fit into a single SKILL.md.

Encoding and formatting. Use UTF-8 encoding and standard line endings. Keep your Markdown clean and well-structured, because the structure itself is a signal to Claude about how to prioritise information.

What the file contains vs what Claude receives. These are not the same. The file contains everything: frontmatter, body, and pointers to resources. What Claude receives at any given moment depends on the disclosure level. At startup it receives only your ~100-token metadata. On invocation it receives the body. It reads referenced files only if the body tells it to. Designing with this transform in mind is the difference between an efficient Skill and one that quietly wastes context.

YAML Frontmatter: Every Field Explained

The frontmatter is small but decisive. Two fields are required (name and description); the rest are optional but valuable at scale. Here is the complete reference.

name, the canonical identifier for the Skill. Use kebab-case, keep it descriptive, and make it unique within your workspace so there is no ambiguity about which Skill is which. code-review-checklist is good; helper is not. The name is both a human label and, in explicit invocation, the thing people call.

version, semantic versioning in MAJOR.MINOR.PATCH form. Bump the PATCH for small fixes and clarifications, the MINOR for new capabilities that stay backward compatible, and the MAJOR for changes that alter existing behaviour in ways that could surprise current users. Versioning is what lets a team know exactly which behaviour they are getting, and it is the backbone of safe iteration. When you re-publish, tag the version in Git so the file history and the version number stay in sync.

description, the single most important field, full stop. It drives invocation routing through semantic matching, and it is always loaded, so it must earn its ~100 tokens. Guidelines that work in practice:

• Aim for roughly 100 to 200 words. Long enough to be specific, short enough to stay in the always-loaded budget.
• Write for semantic similarity, not keyword stuffing. Describe the situations the Skill handles, not a list of keywords.
• Be "pushy" to combat undertriggering. Explicitly list the triggering scenarios, including the implicit ones. Recall Anthropic's example of spelling out that a dashboard Skill should fire whenever a user mentions data visualization or internal metrics, even if they do not explicitly ask for a dashboard.
• A strong description reads: "Reviews code diffs and pull requests against the team's quality checklist and returns findings grouped by severity. Use whenever the user shares a diff, PR, or code snippet for review." A weak one reads: "Helps with code." The first triggers correctly; the second triggers on everything or nothing.

author, individual or team attribution. This matters more than it looks. It establishes accountability (who owns this Skill and who to ask when it misbehaves) and supports governance as your library grows.

tags, a taxonomy strategy for discoverability in large libraries. Recommended categories: domain (security, data, content), function (review, generation, analysis), audience (engineering, support, marketing), and maturity (experimental, stable, deprecated). Consistent tagging is what keeps a 40-Skill library navigable instead of chaotic.

trigger_phrases, an optional array of example utterances that should invoke the Skill. These sharpen invocation scoring by giving Claude concrete anchors. Five to ten is the sweet spot: enough to cover the main phrasings, not so many that you are just restating the description. Note that field support varies by environment, so check the current schema for your setup; where they are not a formal field, fold equivalent examples into the description body.

arguments, definitions for dynamic inputs that callers pass to the Skill. Each argument typically specifies a name, a type, whether it is required or optional, and a default value. Arguments are what make a Skill flexible: a report-generation Skill might take a format argument (default markdown) or a severity_threshold. Keep the argument set minimal and well-documented, because every argument is another thing a caller has to understand and another path you have to test.

Writing an Effective SKILL.md Body

The body is where the actual expertise lives, and the way you write it directly determines how reliably Claude executes.

Match guidance to the task's freedom. Anthropic uses a memorable analogy here. Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom), so match your skill's guidance to the terrain. A compliance-checking Skill needs tight, prescriptive steps. A brainstorming Skill can leave far more room. Do not over-constrain creative tasks and do not under-constrain high-stakes ones.

Structure the body predictably. A reliable pattern is: a one-line statement of the task, a step-by-step procedure, a fixed output format, and a guidelines section that closes loopholes. Anthropic's own workflow examples follow this shape, ending with a quality gate: draft following the header structure and tone guidelines, then run the quality checklist before delivering the draft.

Include examples and validation. Concrete examples anchor Claude's understanding, and explicit validation steps catch errors before they reach the user. When results are inconsistent, the fix is almost always more specificity and more validation, not more length.

Keep it lean. Every line you add loads into context on invocation. The under-500-lines guidance is not arbitrary; it protects your context budget and keeps the important instructions from being diluted.

Using Supporting Files: references, scripts, and assets

The optional directories are how you keep the SKILL.md lean while giving Claude access to more when it needs it. This is the third level of progressive disclosure.

references/ holds documentation Claude loads on demand: detailed specs, long reference tables, style guides. The body points to these files and Claude reads them only when the task calls for it. This is how you handle a Skill with a large knowledge base without paying the context cost on every invocation.

scripts/ holds executable helpers. When a Skill needs to do something deterministic, such as run a linter, parse a file, or call an API, a script is more reliable than asking Claude to simulate the work. The body tells Claude when and how to run each script.

assets/ holds static files: templates, schemas, boilerplate, images. A document-generation Skill keeps its report template here.

The overall principle is elegant. To activate skills, all you need to do is write a SKILL.md file with custom guidance for your agent, and a skill is a directory containing a SKILL.md file with organized folders of instructions, scripts, and resources that give agents additional capabilities. Start with just the SKILL.md and add supporting directories only when the body genuinely outgrows a single file.

Access Control and Packaging for Teams

Two production concerns round out the picture: who can use a Skill, and how you distribute it.

Access control. Set access levels deliberately. Private for development and testing, team or workspace once proven. Because Claude.ai currently scopes Skills to individual users, teams should maintain a shared specification repository in the meantime. It is suggested to create a shared document repository with skill specifications, which prepares your organization for upcoming features while establishing good governance practices today.

Packaging and distribution. Once a Skill is solid, distribute it properly rather than passing files around. The mature path is Git plus plugins plus enterprise settings. You can share skills with your team by committing them to a repository, distribute them more broadly through plugins, and deploy them organization-wide using enterprise managed settings. For governance at scale, Enterprise customers get additional support. Enterprise customers can work with Anthropic's customer success team to explore additional deployment options and governance frameworks.

Testing before distribution. Never distribute a Skill you have not tested against a realistic library of cases. Cover the normal path, the edge cases, and, crucially, the out-of-scope requests that should not trigger the Skill. This last category is how you catch over-triggering before your teammates do.

5. Advanced Patterns: MCP Integration, Subagents, and Tool Approval

Once you are comfortable with single Skills, the real leverage comes from combining them with the rest of the Claude platform. This section covers the patterns that turn a Skill library into genuine automation.

MCP Integration with Claude Skills

The Model Context Protocol connects Claude to external systems: databases, APIs, file stores, internal tools. Skills and MCP are complementary, not competing. MCP provides the connection; the Skill provides the procedure for using that connection well.

A concrete example: MCP connects Claude to your analytics database. On its own, Claude can query it but does not know your table conventions, your definitions of key metrics, or the format your team expects reports in. A Skill supplies all of that. It tells Claude which tables hold which data, how "active user" is defined in your organisation, and exactly how to shape the output. Together they turn a raw connection into a reliable analyst.

Anthropic's example library even includes MCP server generation as one of its demonstrated Skills, underlining how naturally the two layers fit together. When you design a tool-activation Skill, assume MCP is the transport and focus your SKILL.md on the decision logic: when to reach for the tool, what parameters to pass, and how to validate what comes back.

Claude Subagents and Skill Delegation

Subagents let you delegate a bounded task to a separate agent with its own isolated context. Pairing a subagent with a Skill gives you an expert worker for a specific job that does not clutter your main conversation.

The pattern is powerful for multi-step pipelines. Imagine a release workflow: one subagent, armed with a code review Skill, reviews the diff; another, armed with a changelog Skill, drafts release notes; a third, armed with a QA Skill, generates a test plan. Each runs in isolation with only the context it needs. Anthropic describes exactly this capability. You can wire Skills into custom subagents for isolated, expert task delegation, and there is a complete troubleshooting guide for diagnosing issues, from skills that will not trigger to priority conflicts and runtime errors.

The benefit is twofold: cleaner context (the main conversation is not polluted by the subagent's working notes) and clearer specialisation (each subagent does one thing well). The cost is coordination complexity, so reach for subagents when a task genuinely benefits from isolation, not for everything.

Claude Tool Approval and Access Control

When a Skill grants Claude the ability to use tools, especially tools that take real actions like sending emails, writing to a database, or calling a paid API, tool approval becomes a safety-critical concern. The principle is least privilege: a Skill should only unlock the specific tools it genuinely needs, and actions with real consequences should require confirmation.

Design your tool-activation Skills so that read-only operations flow freely but write or destructive operations pause for approval. Document in the SKILL.md body exactly which tools the Skill uses and under what conditions, so that both Claude and any human reviewer understand the blast radius. This is also where the author field and clear versioning earn their keep: when a Skill can take actions, you want unambiguous accountability for who owns it and which version is live.

For organisations, this ties back to enterprise managed settings, where administrators can govern which Skills and tools are available to whom. Treat tool approval as part of Skill design from the start, not a bolt-on. A Skill that can act is a Skill that can cause harm if it triggers wrongly, which is one more reason to scope descriptions tightly and test out-of-scope requests thoroughly.

Skill Testing and Quality Assurance at Scale

Testing a single Skill is easy. Maintaining quality across a growing library requires discipline. Three practices make the difference.

Separate triggering tests from execution tests. As established earlier, these are distinct failure modes. Maintain test cases for each: one set that verifies the Skill fires (and does not fire when it should not), another that verifies the output quality once it does. Test triggering and execution separately; if skills do not activate, broaden your description and add use cases, and if results are inconsistent, add specificity to instructions and include validation steps.

Build a proper test-case library. For each Skill, keep documented cases covering normal usage, edge cases, and out-of-scope requests. Run them whenever you change the Skill. This catches regressions before they reach users and is the single most valuable habit for a maturing library.

Watch for priority conflicts. As your library grows, two Skills with overlapping descriptions will start competing. Part of QA at scale is auditing descriptions for overlap and tightening scope so each Skill owns clear territory. The troubleshooting guides Anthropic provides specifically call out priority conflicts as a known category, so expect them and design against them.

Running Claude across multiple repos all week to test your Skill library? That is often a Max 20x plan at $200/month, billed in USD. With Bleap you pay at the real exchange rate, 0% FX fees, and earn a flat 20% cashback on Claude, ChatGPT, and Gemini renewals, no card subscription required. Get the Bleap card →

6. Production Best Practices and the Smart Way to Pay for Claude

You now have everything you need to build, structure, and combine Skills. Two final pieces make the difference between a hobby and a production practice: operational discipline, and treating the cost of your Claude subscription as something to optimise.

Production Best Practices Checklist

• Scope narrow. Every Skill should do one thing well. Narrow scope means reliable triggering and consistent output.
• Write pushy descriptions. Combat undertriggering by explicitly listing the scenarios that should activate the Skill, including implicit ones.
• Keep bodies lean. Under 500 lines, with detail pushed to references/. Protect your context budget.
• Version everything. Semantic versioning plus Git tags so everyone knows which behaviour is live.
• Test in three buckets. Normal, edge case, and out-of-scope, with triggering and execution tested separately.
• Control access deliberately. Private first, widen only after validation. Least privilege for tools.
• Maintain a spec repository. Especially while org-wide sharing matures, a shared spec repo keeps the team aligned and prepares you for managed settings.
• Document ownership. Use the author field so every Skill has a clear owner.

Follow these and you will build a Skill library that compounds in value rather than accumulating debt.

The Cost Angle: Paying for Claude Without Losing Money

Here is the part most guides ignore. Building Skills means paying for Claude, and Claude subscriptions are billed in USD. Claude Pro is $20/month (or $17/month billed annually), and Claude Max runs $100 to $200/month. For teams, a Team plan starts at $25 per user per month, and $150/month for premium seats that include the Claude Code developer environment.

If you are in the EEA and paying for a USD subscription with a typical European card, you are quietly losing money on every renewal. Most cards add a 2-3% foreign transaction fee on top of a marked-up exchange rate. On a €200-equivalent Max plan, that 2-3% is roughly €4 to €6 a month, or €48 to €72 a year, on FX fees alone. Across a team of five on Team seats, the leakage adds up fast.

This is where Bleap fits into the picture. Bleap is not an AI tool and it will not build your Skills for you. It is a fintech card company, and it is the smart way to pay for the AI subscriptions this guide relies on. Two concrete benefits apply directly here:

• 0% FX fees on USD subscriptions. You pay your Claude Pro, Max, or Team bill at the real exchange rate, with no foreign transaction fee and no weekend markup. The money that would have gone to FX fees stays in your pocket.
• 20% cashback on Claude, ChatGPT, and Gemini. Bleap gives a flat 20% cashback (paid in USDC) on subscriptions to those three specific AI tools. On a $20/month Claude Pro plan that is real money back every single month, and on a $200/month Max plan it is meaningfully more.

It is a self-custodial Mastercard debit card you use anywhere Mastercard is accepted, with no monthly subscription of its own. There is nothing to sacrifice: you keep full control of your funds, you pay your AI bills exactly as before, and you stop leaking money to FX fees while earning cashback on the three biggest AI subscriptions. For anyone running Claude seriously enough to be building Skills, that is a straightforward optimisation.

One honest note: the flat 20% cashback applies specifically to Claude, ChatGPT, and Gemini. For other AI tools you still get the 0% FX fee benefit on USD billing, but not the 20% cashback. And Bleap's savings vaults, which pay 3.65% AER (Steady, lowest risk) and 3.83% AER (Dynamic, low risk) in USD with a $1 minimum and 0% withdrawal fees, are a separate feature worth knowing about if you want your spare balance working while you build.

Frequently Asked Questions

What exactly is a Claude Skill?

A Claude Skill is a self-contained, reusable unit of instruction that Claude loads on demand to perform a specific task reliably. Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks, teaching Claude how to complete specific tasks in a repeatable way. Technically, it is just a folder containing a SKILL.md file with YAML frontmatter and Markdown instructions, plus optional supporting directories.

What is the difference between a skill.md file and a prompt?

A prompt lives for one conversation turn and disappears. A SKILL.md file is persistent, versioned, discoverable, and reusable. The key structural difference is that Claude actively knows a Skill exists, because at startup, the agent pre-loads the name and description of every installed skill into its system prompt. Claude can never reach for a prompt it has not been shown, but it can reach for a relevant Skill automatically.

Do I need to know how to code to build Claude Skills?

No. Skills are fundamentally a writing and configuration discipline. Skills are not models or paid add-ons; they are open-source markdown instructions plus supporting files. If you can write clear instructions in Markdown and think carefully about when a task should trigger, you can build a production-grade Skill. Scripts are optional and only needed for tasks that require deterministic execution.

How does Claude decide when to use a Skill?

Claude matches the current request against the description field of every installed Skill using semantic similarity. Because Claude has a tendency to undertrigger skills, to not use them when they would be useful, Anthropic recommends writing descriptions that explicitly list the scenarios that should activate the Skill, including implicit ones. A strong, specific, slightly pushy description is the single biggest factor in reliable invocation.

How long should a SKILL.md file be?

Keep the body focused. The practical guidance is to keep SKILL.md body to essentials and under 500 lines, and if approaching this limit, split content into separate files. The always-loaded frontmatter is tiny, roughly 100 tokens, while the body loads only when the Skill is invoked, so a lean body protects your context budget and keeps the important instructions from being diluted.

How do Skills relate to MCP and subagents?

They are complementary layers. MCP is the connectivity layer that links Claude to external tools and data; a Skill is the instruction layer that tells Claude how to use that connection. Subagents add isolation, and you can wire Skills into custom subagents for isolated, expert task delegation. A common production pattern combines all three: MCP connects the data, a Skill defines the procedure, and a subagent runs it in a clean context.

Can I share Skills with my whole team?

Increasingly, yes, though the tooling is still maturing. In Claude.ai, Skills are currently individual to each user, though org-wide management and sharing capabilities are coming soon. In the meantime you can share via a Git repository, distribute through plugins, and deploy organization-wide with enterprise managed settings. Maintaining a shared spec repository now prepares you for the managed features to come.

How much does it cost to use Claude for building Skills?

Skill creation itself is part of the Claude plans. Claude pricing in 2026 spans Free ($0), Pro ($20/month), Max 5x ($100/month), Max 20x ($200/month), Team Standard ($25/seat/month), Team Premium ($125/seat/month), and Enterprise (custom). Since these are billed in USD, paying from the EEA with a card that adds a 2-3% foreign transaction fee costs you extra every month. Paying with Bleap gives you 0% FX fees and a flat 20% cashback on Claude subscriptions, so more of your budget goes to actual usage.

What is the most common mistake beginners make with Skills?

Two mistakes tie for first: writing a description that is too vague (so the Skill either never triggers or triggers on everything) and over-stuffing the body. The fix for triggering is a specific, scenario-rich description; the fix for output quality is more specificity and validation, not more length. And always test with a proper case library, because you should create a test case library covering normal usage, edge cases, and out-of-scope requests.

Conclusion

Claude Skills turn ad-hoc prompting into engineered, reusable automation. The core is genuinely simple: a folder, a SKILL.md file with a clear name and a specific, slightly pushy description, and a lean body of instructions Claude loads only when it is relevant. Master that, layer in MCP for connectivity, subagents for isolation, and disciplined testing for reliability, and you have a Skill library that compounds in value across your whole team.

The engineering effort is really a writing effort. Scope narrow, describe precisely, version everything, and test in three buckets. Do that consistently and Claude stops being a general assistant you re-explain things to every morning, and starts being a specialised expert that already knows your workflows.

One last practical tip that has nothing to do with code and everything to do with your budget. Whichever Claude plan you build on, and whichever other AI tools you use alongside it, pay smart. Those subscriptions are billed in USD, and a typical card quietly skims 2-3% on every renewal. With Bleap you skip the FX fees entirely, and on Claude, ChatGPT, and Gemini you earn a flat 20% cashback on every payment, all from a self-custodial Mastercard with no subscription of its own. Build great Skills. Just do not overpay to run them.

You optimised your Claude workflow. Now optimise what you pay to run it. Bleap gives you 0% FX fees on USD subscriptions and a flat 20% cashback on Claude, ChatGPT, and Gemini, with no monthly card fee and full control of your funds. Open a Bleap account →

Bleap's 20% cashback applies to Claude, ChatGPT, and Gemini subscriptions and is paid in USDC. For other AI tools, the 0% FX fee benefit applies to USD billing but the 20% cashback does not. Claude pricing figures are current as of 2026 and set by Anthropic, not Bleap; check Anthropic's official pricing for the latest tiers.