Claude Skills Guide (2026): How to Create, Upload and Use SKILL.md in Claude.ai, Claude Code and the API

If you keep pasting the same long instructions into Claude (“use our brand colors”, “format the report like this”, “run these checks before you commit”), you should turn them into a Skill. A Claude Skill is a folder with a SKILL.md file and, optionally, scripts and reference files. Claude only reads the short name and description until a request matches, then loads the full instructions on demand. That keeps your context window free while giving Claude a library of reusable know-how. This guide shows exactly how to write one, the rules that make a skill trigger reliably, and how to install it on claude.ai, in Claude Code and through the API.

What Are Claude Skills?

Skills (officially Agent Skills) are packages of instructions, metadata and optional resources that Claude uses automatically when they are relevant. The key idea is progressive disclosure: Claude loads a skill in stages, so you can install many without filling the context window.

Scripts run through bash, and only their output enters the conversation, which makes skills a cheap way to give Claude deterministic tools, such as a script that validates a CSV, instead of hoping it does the check correctly in its head.

Anthropic also ships pre-built skills for Word (docx), Excel (xlsx), PowerPoint (pptx) and PDF. They are available on claude.ai and the API, but not in Claude Code.

Skills vs Projects vs CLAUDE.md vs MCP

A simple rule: if it is how to do something, make a skill. If it is access to something, use an MCP server (see my best MCP servers list). If it is facts about this repo, put it in CLAUDE.md.

SKILL.md Format and Rules

my-skill/
├── SKILL.md          # required
├── reference.md      # optional, loaded only if SKILL.md points to it
├── templates/        # optional
└── scripts/
    └── check.py      # optional, run via bash

The required frontmatter:

• name: up to 64 characters; lowercase letters, numbers and hyphens only; no XML tags; must not contain the reserved words “anthropic” or “claude”.
• description: non-empty, up to 1,024 characters, no XML tags. It must say what the skill does and when to use it, because Claude decides whether to trigger the skill by matching your request against this text.

In Claude Code, skills also accept optional fields such as argument-hint and user-invocable (lets you call the skill as a slash command).

Example: A Complete Skill You Can Copy

Here is a small but real skill that turns rough meeting notes into a consistent summary. Save it as meeting-notes/SKILL.md:

---
name: meeting-notes
description: Turn raw meeting notes or a transcript into a structured summary with decisions, action items (owner and due date) and open questions. Use when the user pastes meeting notes, a call transcript, or asks to summarize a meeting.
---

# Meeting notes

## Steps
1. Read the whole input before writing anything.
2. Output these sections in this order:
   - **Summary** (3 sentences max)
   - **Decisions** (bullets)
   - **Action items** as a table: Task | Owner | Due date
   - **Open questions**
3. If an owner or date is missing, write "TBD". Never invent names or dates.
4. Keep the language of the input.

## Example
Input: "Priya will send the deck Friday. We agreed to drop the beta."
Action items: | Send deck | Priya | Friday |
Decisions: - Drop the beta.

Notice the description: it lists the trigger situations (“pastes meeting notes”, “call transcript”, “summarize a meeting”). That is what makes it fire.

How to Upload a Skill to Claude.ai

1. Turn on code execution. Skills run inside Claude’s code execution environment, so enable file creation and code execution in Settings first.
2. Zip the folder that contains SKILL.md (zip the folder itself, not just the file).
3. Upload it in Settings. Anthropic’s docs place this under Settings > Features; some guides describe it as Settings > Customize > Skills. The menu name has moved over time, so look for the Skills section.
4. Test it in a new chat with a request that matches the description.

Plans: Anthropic’s documentation lists custom skill uploads for Pro, Max, Ultra, Team and Enterprise plans with code execution enabled; some third-party guides say the upload works on every plan. Check your own Settings page. On claude.ai, custom skills you upload are personal to you; on Team and Enterprise, admins have additional controls. For plan details see my Claude Free vs Pro vs Max vs Ultra guide.

How to Use Skills in Claude Code

• Personal skills (all projects): ~/.claude/skills/<name>/SKILL.md
• Project skills (commit to git for your team): .claude/skills/<name>/SKILL.md
• Run /skills to list them and /reload-skills after editing.
• Skills can also be distributed inside Claude Code plugins.

In Claude Code, skills have full network access, so a skill script can call your internal APIs. Avoid global package installs inside skill scripts. My Claude Code commands cheat sheet lists every related command and config path.

How to Use Skills With the Claude API

1. Upload: POST /v1/skills with your skill files returns a skill_id. Publish updates with POST /v1/skills/{skill_id}/versions. GET /v1/skills lists both Anthropic and custom skills.
2. Attach: in a Messages request, add a skills list inside the container parameter. Each entry has a type (anthropic or custom), a skill_id and an optional version such as latest. Include the code execution tool in tools.
3. Headers: skills are a beta feature; guides list the code-execution-2025-08-25 and skills-2025-10-02 beta headers. Check Anthropic’s “Using Agent Skills with the API” page for the current values.
4. Files: download generated documents with the Files API.

API limits reported in current guides: up to 8 skills per request, 30 MB per skill, no network access and no runtime package installs inside the container. Custom skills uploaded through the API are shared across your workspace. Skills do not sync between claude.ai, Claude Code and the API, so upload them separately to each. Also note that Agent Skills are not eligible for zero data retention or HIPAA. For token costs, see my Claude API pricing guide.

Tips for Skills That Trigger Reliably

1. Write the description for matching, not for humans. Include the words people actually type: file types, task names, synonyms.
2. One job per skill. A “do everything for marketing” skill triggers randomly. Split it.
3. Keep SKILL.md short and move long references into separate files that SKILL.md links to. They load only when needed.
4. Use scripts for anything that must be exact: validation, calculations, file conversions.
5. Give one worked example. A single input and output pair beats a page of rules.
6. Say what not to do, for example “never invent dates”.
7. Test with five different phrasings and adjust the description until each one triggers.

Security: Treat Skills Like Software

A skill can include scripts that run on your behalf. Anthropic’s own advice:

• Install skills only from trusted sources: your own, or Anthropic’s.
• Read every bundled file before installing, looking for unexpected network calls or file access.
• Be careful with skills that fetch external URLs, since fetched pages can contain hidden instructions (prompt injection).
• Enterprise organizations can turn on skill content scanning for skills uploaded to claude.ai and Claude Cowork; it does not cover API uploads.

Troubleshooting Claude Skills

Most skill problems come down to three things: the file is in the wrong place, the frontmatter did not parse, or the description does not match how people phrase the request. Here is how to tell which one you have.

A quick way to test a new skill

1. Ask Claude “What skills are available?” and confirm yours is listed.
2. Send three requests that should trigger it, worded differently, and one that should not.
3. If one of the should-trigger prompts misses, copy its wording into the description and test again.
4. In Claude Code, run /context to see how much space your skill listing takes. With many skills installed, some descriptions get dropped from the listing to save space, which can stop rarely used skills from triggering.

Frequently Asked Questions

Are Claude Skills free?

Skills are a feature, not a separate product. On claude.ai you need a plan with code execution (Anthropic lists Pro and above for custom uploads). On the API you pay normal token and code execution costs.

Why is my skill not triggering?

Almost always the description. Make it say clearly when to use the skill, with the words users actually type, and keep each skill to one job.

Can I use the same skill in Claude.ai and Claude Code?

Yes, the format is the same, but skills do not sync. Upload the zip to claude.ai and copy the folder into ~/.claude/skills/ separately.

What is the difference between a skill and a subagent in Claude Code?

A skill adds instructions to the current agent when relevant. A subagent is a separate agent with its own context, tools and model, defined in .claude/agents/.

Why was my skill zip rejected on claude.ai?

Usually the zip structure. The archive should contain a single folder named like the skill, with the skill file and any resources inside it, not loose files at the root. Also check the frontmatter starts on the first line and that the description is short enough for the upload form.

How do I make a skill run only when I call it?

In Claude Code, add disable-model-invocation: true to the frontmatter. Claude will no longer load it on its own, and you run it with /skill-name. This suits workflows with side effects, such as deploys or sending messages.

Sources

• Anthropic: Agent Skills overview
• Anthropic: Using Agent Skills with the API
• Claude: How to create Skills, steps and examples
• AgentsCamp: Claude Skills on claude.ai and the API (July 2026)
• ComputingForGeeks: Claude Code cheat sheet (October 2026)