The Complete Guide to Creating and Using Claude Skills 2026

Stop re-explaining yourself. Teach Claude your workflows once and let it handle the rest.

If you’ve been using Claude for a while, you’ve probably noticed the pattern: you explain the same context, the same formatting rules, the same workflow — over and over again, every new conversation.

Skills fix that.

They’re one of the most underused features in Claude right now, and once you start using them, you’ll wonder how you worked without them. In this guide, I’ll walk you through everything: what skills are, how to write one from scratch, how to install and share them, and how to actually make them trigger reliably. Whether you use Claude.ai, Claude Code, or the API, this covers all of it.

Let’s get into it.

---

What Are Skills?

Skills are folders of instructions, scripts, and resources that extend Claude’s capabilities for specialized tasks. Think of them as reusable “expertise packages” — instead of re-explaining a workflow every time, you encode it once as a skill, and Claude applies it automatically whenever it’s relevant.

A skill can be as simple as a few lines of brand guidelines or as complex as a multi-file package with executable Python scripts, templates, and reference documents.

Skills work across Claude.ai, Claude Code, and the API.

---

Prerequisites

• Plan: Free, Pro, Max, Team, or Enterprise

• Code Execution: Must be enabled in Settings → Capabilities

• Enterprise plans: Organization owners must enable both Code execution and Skills in Admin settings before members can use them

• Team plans: Skills are enabled by default at the organization level

---

Part 1: Anatomy of a Skill

Every skill is a folder containing at minimum a SKILL.md file. Here’s what the structure looks like:

my-skill/
├── SKILL.md            ← required (instructions + metadata)
├── scripts/            ← optional: executable code
│   └── process.py
├── references/         ← optional: docs loaded as needed
│   └── style-guide.md
└── assets/             ← optional: templates, fonts, icons
    └── logo.png

The SKILL.md File

This is the core of every skill. It has two parts: YAML frontmatter (metadata) and Markdown body (instructions).

---
name: my-skill-name
description: >
  A clear description of what this skill does and when to use it.
  Include trigger phrases and contexts so Claude knows when to activate it.
---

# My Skill Name

## Overview
What this skill does and why it exists.

## Instructions
Step-by-step guidance for Claude to follow.

## Examples
Show Claude what good output looks like.

Required Metadata Fields

• name — identifier for the skill (use lowercase-kebab-case)

• description — when to trigger and what it does — this is the primary trigger mechanism

Optional Metadata Fields

• dependencies — software packages required by the skill

• license — license information or path to license file

---

Part 2: Writing an Effective SKILL.md

The Description Is Everything

The description field in your frontmatter is the single most important part of your skill. Claude reads every skill’s name and description to decide which skill to load for a given request. If the description doesn’t match, the skill won’t trigger.

Tips for good descriptions:

• Be specific about what the skill does AND when to use it

• Include trigger phrases and contexts

• Be a little “pushy” — Claude tends to under-trigger skills, so err on the side of over-describing when it should be used

• Mention related keywords, file types, and use cases

Bad description:

description: Format data nicely.

Good description:

description: >
  Apply Acme Corp brand guidelines to all presentations, documents,
  and marketing materials. Use this skill whenever the user mentions
  brand colors, typography, company style guide, Acme branding,
  visual identity, or asks for materials that should look “on-brand.”
  Also use when creating any client-facing deliverable.

Writing the Instruction Body

The body of SKILL.md is where you tell Claude how to do the work. Follow these principles:

1. Explain the “why,” not just the “what”

Claude is smart. If you explain why something matters, it can generalize better than if you give rigid rules.

<!-- Instead of this -->
ALWAYS use 14pt font for body text.

<!-- Do this -->
Use 14pt font for body text — this ensures readability
when printed or projected, which is common for these deliverables.

2. Use imperative form

Write instructions as direct commands.

## Steps
1. Read the uploaded file
2. Extract all table data
3. Reformat using the template in assets/template.xlsx
4. Save the output as a new file

3. Include examples

Examples are one of the most effective ways to steer Claude’s behavior.

## Commit Message Format

**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

**Example 2:**
Input: Fixed crash when clicking submit with empty form
Output: fix(forms): handle empty form submission gracefully

4. Define output formats explicitly

## Report Structure
ALWAYS use this template:

# [Title]
## Executive Summary
## Key Findings
## Recommendations
## Appendix

Progressive Disclosure

Skills use a three-level loading system to be efficient:

1. Metadata (name + description) — Always loaded (~100 words). Claude uses this to decide if the skill is relevant.

2. SKILL.md body — Loaded when the skill triggers. Keep under ~500 lines.

3. Bundled resources (scripts, references, assets) — Loaded on demand. Can be unlimited size.

If your skill is getting long, move detailed reference material into references/ files and point to them from SKILL.md:

## Supported Platforms
For platform-specific instructions, read the appropriate reference file:
- AWS: `references/aws.md`
- GCP: `references/gcp.md`
- Azure: `references/azure.md`

---

Part 3: Adding Scripts and Resources

Executable Scripts

For tasks that benefit from deterministic code (data processing, file conversion, chart generation), bundle scripts in a scripts/ directory.

my-skill/
├── SKILL.md
└── scripts/
    ├── generate_chart.py
    └── process_data.py

In your SKILL.md, reference them:

## Chart Generation
Run `scripts/generate_chart.py` with the input CSV to produce
the visualization. The script accepts:
- `--input`: path to the CSV file
- `--output`: path for the output PNG
- `--style`: one of “minimal”, “corporate”, “colorful”

Note on dependencies: Claude can install packages from PyPI (pip) and npm at runtime in Claude.ai and Claude Code. For API usage, all dependencies must be pre-installed in the container. List them in your frontmatter:

dependencies:
  - python-pptx
  - pandas
  - matplotlib

Reference Files

For large bodies of knowledge that Claude should consult selectively:

my-skill/
├── SKILL.md
└── references/
    ├── api-v1.md
    ├── api-v2.md
    └── migration-guide.md

Assets

For templates, images, fonts, or other files used in output:

my-skill/
├── SKILL.md
└── assets/
    ├── report-template.docx
    ├── company-logo.png
    └── fonts/
        └── BrandFont.ttf

---

Part 4: Example Skills

Simple Skill — Brand Guidelines

---
name: brand-guidelines
description: >
  Apply Acme Corp brand guidelines to presentations, documents,
  and marketing materials. Use whenever the user mentions brand
  colors, typography, company style, or creates client-facing content.
---

# Acme Corp Brand Guidelines

## Colors
- Primary: `#1a2b3c` (Navy)
- Accent: `#e74c3c` (Red)
- Background: `#f8f9fa` (Light Gray)
- Text: `#2c3e50` (Dark Gray)

## Typography
- Headings: Montserrat Bold
- Body: Open Sans Regular
- Code: JetBrains Mono

## Voice & Tone
- Professional but approachable
- Active voice preferred
- Short sentences for clarity

Medium Skill — Code Review Helper

---
name: code-review
description: >
  Review code for quality, security, and best practices. Use when
  the user asks for a code review, wants feedback on their code,
  asks “is this code good?”, or submits a pull request for review.
---

# Code Review Skill

## Review Checklist

When reviewing code, evaluate each of these areas:

1. **Correctness**: Does the code do what it claims?
2. **Security**: Are there injection risks, exposed secrets,
   or missing input validation?
3. **Performance**: Any N+1 queries, unnecessary loops,
   or missing caching opportunities?
4. **Readability**: Clear naming, appropriate comments,
   consistent formatting?
5. **Testing**: Are edge cases covered? Are tests meaningful?

## Output Format

Structure every review as:

### Summary
One paragraph overall assessment.

### Issues Found
List each issue with severity (critical / warning / suggestion),
file and line reference, and a recommended fix.

### What’s Done Well
Highlight 2-3 things the code does right — reviews shouldn’t
only be negative.

Advanced Skill — With Scripts

data-dashboard/
├── SKILL.md
├── scripts/
│   └── build_dashboard.py
└── assets/
    └── dashboard_template.html

---
name: data-dashboard
description: >
  Create interactive data dashboards from CSV or Excel files.
  Use when the user wants to visualize data, create a dashboard,
  make charts from a spreadsheet, or says “show me this data.”
dependencies:
  - pandas
  - plotly
---

# Data Dashboard Skill

## Workflow
1. Read the user’s data file (CSV, XLSX, or TSV)
2. Analyze columns and data types automatically
3. Run `scripts/build_dashboard.py` to generate the dashboard
4. Output an interactive HTML file

## Script Usage
```bash
python scripts/build_dashboard.py \
  --input data.csv \
  --output dashboard.html \
  --title “Q3 Sales Dashboard”

Chart Selection Guide

• Time series data → Line chart

• Categorical comparisons → Bar chart

• Part-to-whole → Pie or donut chart

• Correlations → Scatter plot

• Distributions → Histogram

---

Part 5: Installing Skills

In Claude.ai (Web / Desktop / Mobile)

1. Go to Settings → Customize → Skills (or the Customize panel)

2. Click Upload Skill

3. Select your .zip or .skill file

4. Claude reads your SKILL.md and displays the skill details

5. Toggle the skill on to activate it

Packaging your skill for upload:

• Put your skill folder inside a ZIP file

• The ZIP should contain the skill folder as its root (not nested inside another folder)

• The folder name should match your skill’s name field

my-skill.zip
└── my-skill/
    ├── SKILL.md
    └── scripts/
        └── process.py

In Claude Code (Terminal)

Place skills in one of these locations:

Project-level (shared with your repo):

your-project/
└── .claude/
    └── skills/
        └── my-skill/
            └── SKILL.md

User-level (available across all projects):

~/.claude/skills/my-skill/SKILL.md

Claude Code discovers and loads skills automatically. You can also invoke them directly with /my-skill-name.

Via the API

Upload skills using the Skills API:

curl -X POST “https://api.anthropic.com/v1/skills” \
  -H “x-api-key: $ANTHROPIC_API_KEY” \
  -H “anthropic-version: 2023-06-01” \
  -H “anthropic-beta: skills-2025-10-02” \
  -F “display_title=My Skill Name” \
  -F “files[]=@my-skill/SKILL.md;filename=my-skill/SKILL.md”

---

Part 6: Sharing Skills

On Team and Enterprise Plans

In Customize → Skills, open a skill you created. You can share it with:

• Specific people: Enter names or emails. The skill appears in their skills list (grayed out until they enable it).

• Entire organization: Published to your org’s directory where anyone can find and install it.

Shared skills are view-only — recipients can enable and use them but can’t edit them. Updates you make are automatically pushed to recipients.

Exporting for Others

Package your skill folder as a .zip file and share it directly. Recipients upload it through their own Skills settings.

---

Part 7: Testing and Iterating

Manual Testing

After uploading your skill:

1. Open a new chat

2. Ask Claude something that should trigger your skill — try both explicit mentions (”Use my brand guidelines skill to...”) and implicit triggers (”Create a client-facing presentation”)

3. Check that the output follows your instructions

4. Test edge cases and unexpected inputs

Using the Skill Creator

Claude has a built-in skill for creating and improving skills. You can use it by asking Claude directly:

“I want to create a skill that does X. Can you help me build it?”

The skill creator walks you through:

1. Defining what the skill should do

2. Writing a draft SKILL.md

3. Creating test cases

4. Running test prompts

5. Evaluating results

6. Iterating until you’re satisfied

7. Packaging the final skill

Troubleshooting

Skill doesn’t trigger:

• Broaden your description field — add more trigger phrases and contexts

• Be more explicit in your prompt: “Use my [skill-name] skill to...”

• Ensure the skill is toggled on in Customize → Skills

• Verify code execution is enabled

Inconsistent results:

• Add more specificity to your instructions

• Include concrete examples of expected output

• Add validation steps (”Before outputting, verify that...”)

Errors when running scripts:

• Check that dependencies are listed in frontmatter

• Verify scripts work standalone before bundling

• Check file paths are relative to the skill directory

---

Part 8: Best Practices

Do

• Keep skills focused. One skill per workflow. Multiple focused skills compose better than one massive skill.

• Write clear descriptions. This is the trigger mechanism — invest time here.

• Include examples. They’re the most effective way to steer output quality.

• Explain the why. Claude generalizes better from reasoning than from rigid rules.

• Test with realistic prompts. Use the kind of language real users actually type, including casual phrasing and typos.

• Iterate. The first draft is rarely the best. Test, get feedback, improve.

• Use progressive disclosure. Keep SKILL.md lean; put detailed references in separate files.

Don’t

• Don’t make skills too broad. A skill that tries to do everything will do nothing well.

• Don’t rely on ALL-CAPS rules. Explaining why something matters is more effective than shouting.

• Don’t skip the description. Without a good description, Claude won’t know when to use your skill.

• Don’t hardcode paths or environments. Skills should be portable across surfaces.

• Don’t assume your skill runs in isolation. Claude can load multiple skills simultaneously.

Security Considerations

• Review skills from external sources before enabling them — check bundled scripts and dependencies

• Skills can instruct Claude to install third-party packages, which carries inherent risk

• Be cautious of skills that instruct Claude to connect to external network sources

• Never include API keys, passwords, or secrets in skill files

---

Part 9: Skill Patterns by Use Case

• Brand guidelines — colors, fonts, tone, logo usage rules

• Document templates — structure, formatting, example sections, assets

• Code standards — linting rules, naming conventions, review checklists

• Data workflows — processing scripts, output formats, chart preferences

• Writing style — voice, tone, word choices, formatting, examples

• API integration — endpoint docs, auth patterns, request/response examples

• Onboarding guides — step-by-step processes, checklists, reference docs

---

Quick-Start Checklist

1. ☐ Create a folder named after your skill (lowercase-kebab-case)

2. ☐ Write a SKILL.md with YAML frontmatter (name + description)

3. ☐ Write clear instructions in the Markdown body

4. ☐ Add examples of expected input and output

5. ☐ (Optional) Add scripts/, references/, or assets/ folders

6. ☐ ZIP the folder (skill folder as root of the archive)

7. ☐ Upload in Customize → Skills

8. ☐ Toggle the skill on

9. ☐ Test with realistic prompts

10. ☐ Iterate based on results

---

What’s Next

That’s the full picture — from a blank folder to a production-ready skill running across Claude.ai, Claude Code, and the API. If you build something cool, I’d love to hear about it. Reply to this email or tag me — I might feature it in a future issue.

Coming up in the newsletter: more deep dives on Claude’s tooling ecosystem, practical AI workflows for dev teams, and hands-on guides like this one. If you found this useful, share it with a colleague who’s still copy-pasting the same prompt every morning.

---

More from AI For Developers

This newsletter is part of AI For Developers — a growing directory of AI developer tools, APIs, frameworks, and resources. If you’re evaluating tools for your stack or just want to stay on top of what’s out there, check it out:

🔗 AI For Developers — Browse the directory

📬 AI For Developers newsletter — Subscribe to the newsletter

Every issue covers one topic in depth — no fluff, no hype, just the stuff you need to build with AI. Subscribe if you haven’t already, and I’ll see you in the next one.