Claude Code Skills: How to Set Them Up and Use Them

Teach Claude once, use it every time.

Reading time: 10 minutes | Difficulty: Beginner-friendly

You’ve probably repeated the same instructions to Claude over and over: “Use our style guide,” “Always run tests before committing,” “Format the output like this.” Skills fix that. A skill is a small folder of instructions that teaches Claude how to handle specific tasks or workflows so you don’t have to re-explain every time. This guide walks you through what they are, how to set them up, and how to use them—based on the official Complete Guide to Building Skills for Claude.

📁 What Are Claude Skills?

A skill is a folder that contains:

• SKILL.md (required) — Instructions in Markdown with YAML frontmatter that tell Claude when to use the skill and what to do.
• scripts/ (optional) — Executable code (Python, Bash, etc.) the skill can call.
• references/ (optional) — Extra docs Claude can open only when needed.
• assets/ (optional) — Templates, fonts, or images used in the workflow.

Skills work well when you have repeatable workflows: turning specs into frontend designs, running research with a consistent method, or generating documents that follow your team’s style. They also pair powerfully with MCP (Model Context Protocol): MCP gives Claude access to tools and data; skills teach Claude the best way to use them.

Three-Level Design: Progressive Disclosure

Skills use a simple three-level system so Claude stays fast and focused:

That way Claude doesn’t load every word of every skill—only what’s needed for the current task.

⚙️ How to Set Up a Skill (Structure and Frontmatter)

Folder and File Rules

• Folder name: Use kebab-case only. Examples: notion-project-setup ✅ — not Notion Project Setup ❌ or notion_project_setup ❌.
• Main file: Must be named exactly SKILL.md (case-sensitive). No skill.md or SKILL.MD.
• No README.md inside the skill folder. Put all instructions in SKILL.md or under references/.

YAML Frontmatter: The Most Important Part

The frontmatter is how Claude decides whether to load your skill. It sits at the top of SKILL.md between --- lines.

Minimum you need:

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

• name — kebab-case, no spaces or capitals. Should match the folder name.
• description — Must include both:
  • What the skill does.
  • When to use it (trigger phrases or situations).

Keep the description under 1024 characters. Do not use XML angle brackets (< or >); they’re not allowed for security reasons.

Good description example:

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

Bad: “Helps with projects.” (Too vague, no triggers.)

Optional frontmatter: license, compatibility, metadata (e.g. author, version, mcp-server). See the official guide for the full list.

✍️ Writing Instructions That Work

After the frontmatter, write the actual instructions in Markdown.

Best practices:

• Be specific and actionable. Prefer “Run python scripts/validate.py --input {filename}” over “Validate the data before proceeding.”
• Include error handling. Add a “Common issues” or “Troubleshooting” section (e.g. “If you see ‘Connection refused’, check that the MCP server is running in Settings > Extensions”).
• Reference bundled resources clearly. e.g. “Before writing queries, consult references/api-patterns.md for rate limiting and pagination.”
• Use progressive disclosure. Keep SKILL.md focused; move long reference material into references/ and link to it.

For critical checks, consider bundling a small script that runs the validation. Code is deterministic; natural-language instructions can be interpreted differently. The official Office-related skills use this pattern.

📍 Using Skills: Where They Live and How They Load

Where to Put Skills

How Claude Loads Them

• Automatic — Claude reads the description (and other frontmatter) and loads the skill when the user’s request matches.
• Slash commands — In supported environments you can invoke manually, e.g. /your-skill-name.

Enabling in Claude.ai

1. Go to Settings → Capabilities.
2. Turn on Code execution and File creation if your skill uses them.
3. Use Upload skill and select your skill folder (as a ZIP if required).
4. Toggle the skill on.

Skills follow the Agent Skills open standard, so the same skill can work across Claude.ai, Claude Code, and the API where supported.

🧪 Testing and Iterating

Before and after upload, validate your skill:

Triggering:

• ✅ Loads on obvious requests (e.g. “Help me set up a new ProjectHub workspace”).
• ✅ Loads on paraphrased requests (“I need to create a project in ProjectHub”).
• ❌ Does not load on unrelated topics (“What’s the weather?”).

Execution:

• Run the workflow and check that outputs and tool calls are correct.
• If you use MCP, confirm the skill uses the right tools in the right order.

Using the skill-creator skill:

• In Claude.ai (or Claude Code if available), you can say: “Use the skill-creator skill to help me build a skill for [your use case].” It helps generate frontmatter, suggest trigger phrases, and review structure. It doesn’t run automated test suites, but it’s useful for design and refinement.

If the skill under-triggers: Add more concrete trigger phrases and keywords to the description.
If it over-triggers: Narrow the description or add negative triggers (e.g. “Do NOT use for simple data exploration”).

🎯 When to Use Skills vs. “Just Prompt”

Skills shine when:

• You have repeatable workflows (sprint planning, design handoff, report generation).
• You want consistent quality (style guides, checklists, templates).
• You’re combining MCP + skills (tools + recipes): MCP gives access; skills give the methodology.

When you need custom agents, production-scale systems, or multi-agent architecture, skills are one building block—but you may also need proper agent design and validation. If you’re exploring whether an agentic AI concept is feasible for your product, our Agentic AI Feasibility Assessment can help you validate the idea, choose an architecture, and plan tool integration before you build.

🔜 Conclusion and Next Steps

Recap: Skills are reusable instruction sets that teach Claude when and how to do specific tasks. Get the folder name (kebab-case), SKILL.md, and frontmatter (especially name and description) right, and keep the main instructions clear and actionable. Use the skill-creator to draft and refine, and test both triggering and execution.

Next steps:

• Try one small skill (e.g. “Format my meeting notes as bullet points”) and iterate.
• Read the full Complete Guide to Building Skills for Claude.
• If you’re building agentic workflows at scale, consider an Agentic AI Feasibility Assessment to align skills and tools with your product goals.

Last updated: February 2026