Building Skills for Claude: The Complete Guide
A skill is a folder containing instructions that teach Claude how to handle specific tasks or workflows. Instead of re-explaining your context, preferences and expertise in every conversation, you teach Claude once and benefit every time. This guide covers everything you need to build effective skills from scratch.
What is a Claude Skill?
A skill is a folder that provides Claude with structured process knowledge. It consists of a few files that together define when and how Claude should execute a particular workflow.
Anatomy of a Skill
- SKILL.md (required): Instructions in Markdown with YAML frontmatter - the core of the skill
- scripts/ (optional): Executable code (Python, Bash, etc.) for deterministic tasks
- references/ (optional): Documentation loaded on demand
- assets/ (optional): Templates, fonts, icons for output generation
Skills are the opposite of ad-hoc prompting. They make workflows reproducible, testable and suitable for team use. They work best for recurring processes where consistency and quality matter more than improvisation.
The Three Core Principles
Effective skills are built on three principles. They determine how you structure your skill and how Claude uses it.
A three-level system: YAML frontmatter is always loaded. SKILL.md content is loaded when relevant. Linked files are loaded only when needed. This keeps token usage low while preserving full expertise.
Claude can load multiple skills simultaneously. Your skill should work well alongside others, not assume it is the only one active. Keep the focus precise and avoid overlap with other skills.
Skills work identically on claude.ai, in Claude Code and via the API - provided the environment supports all dependencies. Build once, use everywhere.
Skills and MCP Servers: The Combination
If you already operate a working MCP server, you have done the hard part. Skills are the knowledge layer on top. They capture workflows and best practices so Claude can apply them consistently.
The Kitchen Analogy
MCP provides the professional kitchen: tools, ingredients and equipment. Skills provide the recipes: step-by-step instructions for creating something valuable. Together they enable complex tasks without users needing to figure out every step themselves.
Connects Claude to your services (Notion, Asana, Linear). Provides real-time data access and tool invocation.
Teaches Claude how to use your services effectively. Captures workflows and best practices in every interaction.
Users connect MCP but do not know what to do next. Support tickets, inconsistent results, frustrated users.
Pre-built workflows activate automatically. Lower learning curve, consistent results, lower support burden.
For teams building agentic AI integrations , skills are the logical next step - turning raw tool access into reliable, optimised workflows.
Planning: How to Start Right
Before writing a single line, identify two to three concrete use cases. A well-defined use case describes precisely what a user wants to accomplish, which tools are required and what domain knowledge should be embedded.
The Three Skill Categories
Creating consistent, high-quality output: documents, presentations, apps, designs, code. Embedded style guides and templates. No external tools required.
Multi-step processes with consistent methodology. Coordination across multiple MCP servers. Step-by-step validation and iterative refinement loops.
Workflow guidance on top of existing MCP access. Embedded domain expertise. Error handling for common MCP issues specific to your integration.
Technical Requirements
Folder structure and naming follow strict rules you should apply from the start:
Mandatory Rules
-
File name:
Exactly
SKILL.md(case-sensitive - no variations accepted) -
Folder name:
kebab-case:
my-skill-name- no spaces, no capitals, no underscores - No README.md inside the skill folder (only at repository root for GitHub users)
- No "claude" or "anthropic" in the skill name (reserved by Anthropic)
The YAML Frontmatter: The Most Important Part
The YAML frontmatter determines whether Claude loads your skill at all. Claude reads the name and description and then decides whether the skill is relevant to the current task.
Minimal Required Format
---
name: your-skill-name
description: What it does. Use when user mentions [specific phrase].
---The description must contain TWO things: what the skill does AND when to use it (trigger conditions). Maximum 1024 characters, no XML angle brackets.
kebab-case only. No spaces or capitals. Should match the folder name exactly.
What + When. Include trigger phrases. Mention relevant file types. Stay under 1024 characters.
Custom fields: author, version, mcp-server, category, tags, documentation, support contact.
Writing Effective Instructions
The content of the SKILL.md body determines output quality. Concrete, actionable instructions are essential - vague guidance produces inconsistent results.
Instead of "validate the data": "Run
python scripts/validate.py --input {filename}
. If validation fails, common issues include missing required fields and invalid date formats (use YYYY-MM-DD)."
Document common errors and their solutions. Particularly for MCP integrations: what to do on "Connection refused" or expired API keys? Give users a clear recovery path.
Move detailed documentation to
references/
and link to it explicitly. Keep the main SKILL.md focused on core instructions and quick to load.
Keep SKILL.md under 5,000 words. Put details in
references/
. Claude loads sub-files only when needed - this saves context and improves accuracy on long tasks.
Testing and Iteration
Skills are living documents. Plan for iteration from the start. The most effective skill builders iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill.
1) Trigger Tests
Test 10-20 queries that should trigger the skill, and queries that should not. Aim for 90% correct recognition across varied phrasings.
2) Functional Tests
Run the complete workflow with real test data. Check output quality, API error rate and token consumption compared to baseline.
3) Performance Comparison
Compare the same task with and without the skill. Count messages, API calls, tokens and how often the user needs to correct or redirect Claude.
4) Use skill-creator
The built-in skill-creator skill helps you build, review and refine skills. Ask: "Help me build a skill for [use case] using skill-creator."
5) Read the Signals
Under-triggering: refine description, add more trigger phrases. Over-triggering: add negative triggers, be more specific. Execution errors: improve instructions, add error handling.
Proven Practical Patterns
These patterns emerged from early adopters and internal teams building skills across a wide range of industries and use cases.
Multi-step processes in a specific order. Explicit step dependencies. Validation at each stage. Rollback instructions on failure.
Workflows spanning multiple services. Clear phase separation. Data passing between MCPs. Centralised error handling for the full pipeline.
Initial draft, quality check via script, improvement loop, finalisation. Output quality improves with each iteration cycle.
Embedded expertise beyond tool access: compliance checks, industry-specific rules, institutional decision logic baked into every run.
Skills for European Organisations: Governance and Compliance
Skills offer European organisations a concrete path to making AI workflows reproducible, auditable and compliant. This is particularly relevant in the context of GDPR and the EU AI Act.
Security Requirements
What You Should Ensure
- Never embed API keys or passwords in SKILL.md or reference files
- Verify and document third-party packages in scripts before deployment
-
Configure least-privilege with
allowed-toolsin Claude Code - Define an internal approval process and complete it before production use
- Code execution runs in a sandbox without cross-session persistence
Concrete Use Cases for European Enterprises
Reports, proposals, meeting minutes in your corporate style - automatically and consistently.
Reproducible pipelines for recurring analyses instead of one-off prompt experiments.
Onboarding, quality checks, customer correspondence - standardised and auditable.
Expert knowledge as shareable Project Skills via Git. No more knowledge silos or tribal prompting.
Distribution and Sharing
Skills can be distributed in several ways - for individual users, teams and entire organisations. Since December 2025, administrators can roll out skills workspace-wide.
Download the skill folder, compress as ZIP and upload via Settings. Ideal for manual testing and individual workflows.
Use the
/v1/skills
endpoint for programmatic management. The
container.skills
parameter in the Messages API targets production systems, automated pipelines and agent architectures.
Admins deploy skills across the full workspace. Automatic updates, centralised management. Version control via the Claude Console.
As an open standard, Agent Skills is designed so that skills remain portable across AI platforms. Platform-specific requirements are documented in the
compatibility
field of the SKILL.md. For a deeper look at
Claude Code and agentic software development
, see our dedicated article.
Common Problems and Solutions
Most problems with skills trace back to a handful of root causes. Here is how to diagnose and fix them.
File name must be exactly
SKILL.md
(case-sensitive). YAML frontmatter must open and close with
---
delimiters. Skill name must be kebab-case only.
Description too generic ("helps with projects"). Missing trigger phrases that users actually say. Missing mention of relevant file types handled by the skill.
Add negative triggers: "Do NOT use for..." Make the description more specific. Explicitly name counterexamples that should not activate the skill.
Place critical instructions at the top. Use
## Critical
headers. Replace vague phrasing with concrete steps. Move detail to
references/
and keep SKILL.md focused.
Conclusion: Skills as the Foundation for Scalable AI
Claude Skills are more than a technical feature. They are the mechanism by which organisations structure AI work, make it auditable and scale it. With a clear use case, a precise description and well-considered instructions, you can have a first working skill up and running in 15-30 minutes.
Key Takeaways
- Skills = folder with SKILL.md, optional scripts, references and assets
- Progressive Disclosure: YAML always, SKILL.md when relevant, files when needed
- The description determines whether the skill triggers - precision here is everything
- Skills + MCP = tool access plus embedded process knowledge
- Test, iterate, version - skills are living documents, not one-off configurations
- Organisation-wide rollout possible since December 2025
Teams that start building skills today lay the groundwork for AI usage that does not depend on the luck of a clever prompt - but on solid, documented processes. For a broader view of agentic AI adoption in Europe , see our analysis article.