Claude Skills: What They Are and How to Build One

Claude skills are folders of instructions, scripts and reference files that Claude loads only when a task needs them. Each one has a SKILL.md file with a name, a description of when to use it, and the steps to follow.

You write the process once, and Claude applies it every time it fits.

I run a good part of my business on skills. One audits every blog post against 38 on-page rules and refuses to pass a draft that breaks them. Another turns a keyword list into a brief with the thresholds the writer must hit. This guide explains how skills work, and how to build one that Claude actually reaches for.

What are Claude skills?#

Anthropic's help center defines skills as folders that Claude loads dynamically to get better at specialized tasks, whether that's applying brand guidelines, following a company's analysis workflow or automating a personal routine. The official overview puts it more practically: skills turn a general-purpose agent into a specialist.

There are four kinds:

• Anthropic skills for creating Word, Excel, PowerPoint and PDF files, used automatically in claude.ai.
• Custom skills you or your team write.
• Organization skills that Team and Enterprise owners provision for everyone.
• Partner skills in the Skills Directory from companies such as Notion, Figma and Atlassian.

Skills are also an open standard. The specification lives at agentskills.io, so a skill you write isn't locked to Claude.

How do Claude skills work?#

The key idea is progressive disclosure. Claude doesn't load every skill into memory. It loads them in three stages:

That's why you can install dozens of skills without slowing Claude down. It also explains a subtle benefit: when a skill runs a bundled script, only the script's output enters the context, not the code. A validation script is far cheaper than asking Claude to reinvent the check every time.

Where can you use skills?#

One gotcha the docs are explicit about: skills don't sync across surfaces. A skill uploaded to claude.ai isn't available in the API, and a Claude Code skill lives on your filesystem. Keep your skills in a Git repository and deploy them to each place you need.

In Claude Code, the folder name becomes a slash command. A skill saved at .claude/skills/deploy-staging/SKILL.md runs as /deploy-staging, and Claude can also load it on its own when a request matches.

How to create a Claude skill#

A skill needs only one file. Here's a small, real-world example:

---
name: summarizing-changes
description: Summarize uncommitted changes as release notes for non-technical readers. Use when the user asks what changed, wants release notes, or is preparing a changelog.
---
 
# Summarizing changes
 
1. Run `git diff --stat` and `git diff` to see what changed.
2. Group changes by user-visible effect, not by file.
3. Write one plain-English bullet per effect. No file names or jargon.
4. End with a "Needs attention" list for anything risky or unfinished.

Save it as ~/.claude/skills/summarizing-changes/SKILL.md and ask Claude Code "what changed today?". The description matches, so the skill loads.

The frontmatter has two required fields, with rules enforced when you upload a skill to claude.ai or the API:

• name: up to 64 characters, lowercase letters, numbers and hyphens only, and it can't contain "claude" or "anthropic".
• description: up to 1,024 characters, and it must say both what the skill does and when to use it.

In Claude Code you can add optional fields. disable-model-invocation: true means only you can trigger the skill, which is what you want for anything with side effects, like a deploy. allowed-tools pre-approves specific tools while the skill runs. The Claude Code skills documentation lists the rest.

How do you write skills Claude actually uses?#

Most skills that "don't work" have a vague description. Claude matches your request against that one sentence, so write it like a trigger, not a tagline. Beyond that, Anthropic's authoring best practices boil down to a few habits:

1. Be concise. Claude is already smart. Only add context it doesn't have, such as your conventions, thresholds and edge cases.
2. Keep SKILL.md under 500 lines. Move detail into reference files, and link them directly from SKILL.md, only one level deep.
3. Name skills with gerunds, like processing-pdfs or auditing-content, so they describe an activity.
4. Use scripts for anything that must be exact. Instructions guide; code enforces.
5. Build evaluations first. Write three scenarios where Claude currently fails, then write just enough instructions to pass them.
6. Avoid time-sensitive facts that will quietly go stale.

The fourth habit is the one I lean on hardest. My content-audit skill doesn't ask Claude to judge whether a title is too long; it runs a script that counts characters and exits with an error. That's the difference between a skill that suggests and a skill that gates.

Where to find good Claude skills#

• Anthropic's repository. The anthropics/skills repo holds example skills for creative, technical and enterprise work, plus the document skills behind Claude's file creation. In Claude Code, add it with /plugin marketplace add anthropics/skills.
• Community collections. Marketing, design and engineering teams publish their own. I review the best marketing set in Claude marketing skills.
• Your own work. The best skill is usually the process you explain to a new colleague twice a month.

A security note the docs repeat for good reason: a skill can run code and call tools, so treat installing one like installing software. Read every file first, and be careful with skills that fetch content from external URLs.

Skills vs projects, MCP and CLAUDE.md#

Skills overlap with other Claude features, and picking the wrong one is the most common setup mistake:

• Projects hold background knowledge that's always loaded in that project's chats.
• MCP connects Claude to outside tools and data; skills teach Claude how to use them.
• CLAUDE.md holds rules that apply to every session in a repository. My guide to writing CLAUDE.md covers when to move a rule from there into a skill.

I break down when to use skills, subagents or MCP servers in Claude skills vs agents vs MCP. And if you'd like to build your first real skills on your own work with feedback, week two of my Claude Code course is dedicated to them.