What is a Skill? How to Create and Use Skills to Make AI Do the Right Work, the Right Way

What is a Skill? A Skill is a named package of guidance that Claude retrieves and uses when encountering the right type of work, instead of you having to paste the same instructions every week. Imagine sentences like "write a report using this template," "review code against that checklist," or "name files according to company rules"—each time you paste is extra work, and AI could still get it wrong somewhere. According to Anthropic's Agent Skills documentation (Claude platform, Claude Code), a skill is a directory with SKILL.md as its center; the name declaration is capped at 64 characters and description at 1024 characters. This post walks you through creating a skill, how Claude loads skills in three layers, how to use it in Claude Code, Claude.ai, and API, plus two hypothetical examples for small business and a 15-minute checklist to get your first skill. For example, the summarize-changes skill below contains just a few lines.

What is a Skill?

A Skill (full name Agent Skill) is a directory containing guidance for Claude to do one specific type of work, according to Anthropic's Agent Skills documentation. The center of the directory is the SKILL.md file. It can also come with scripts, template files, and reference documents. For instance, an accounting office could save file naming rules and data verification procedures as a skill, instead of repeating them in every chat.

A skill has two parts in SKILL.md:

• Frontmatter (YAML, between two --- lines): declares name and description.
• Content: the steps Claude needs to take, rules, examples.

Example of the smallest possible working skill:

---
name: summarize-changes
description: Summarize uncommitted code changes and point out risks. Use when the user asks "what did I just change" or before committing.
---

## Current changes

!`git diff HEAD`

## How to do it

1. Summarize changes in 3–5 bullet points.
2. List risks: sensitive files, large changes, missing tests.
3. Suggest one commit message.

That alone gives Claude a "process" to call back anytime.

How is a Skill different from a prompt, and different from MCP?

A Skill differs from a prompt in that it's saved ahead of time and loaded automatically, and it differs from MCP in that a skill is process guidance while MCP is a connection to outside systems. These three things complement each other:

	Prompt	Skill	MCP
What is it	A command you type each time	A saved instruction package that Claude auto-loads when needed	A gateway connecting AI to tools/data outside
Use when	One-off work	Repeated work that needs to be done one correct way	AI needs to read/write another system (calendar, CRM, database)
Located in	Inside the chat	A file directory on your machine or account	One server connection

Remember it this way: a prompt is a reminder, a skill is a procedure handbook, an MCP is hands touching another system. These three things support each other but don't replace each other.

How does Claude use a skill?

The advantage of skills is that you don't pack everything into context right from the start. According to Anthropic's official documentation, skills load in three layers (a "progressive disclosure" mechanism):

1. Metadata (name and description): always loaded, so Claude knows which skills exist.
2. Guidance in SKILL.md: loaded only when your request matches the skill.
3. Reference files and scripts: loaded or run only when truly needed. Scripts run via bash and Claude only gets the output, so it's stable and saves tokens.

Practical consequence: you can install many skills without "bloating" each chat. And because Claude decides whether to use a skill based on the description, description is the most important part of a skill.

What makes a good skill to write?

1. Description states both "what to do" and "when to use it."
Claude matches your request against the description to pick a skill. Vague writing means the skill never gets called.

• Weak: Helps with reporting.
• Good: Create weekly sales reports from Excel files using company template. Use when the user asks for a weekly report, sales totals, or to send figures to the director.

2. Follow frontmatter rules.
Per Agent Skills documentation: name is at most 64 characters, only lowercase letters, numbers, and hyphens; description cannot be empty and is at most 1024 characters.

3. Start with work you're already repeating.
When you catch yourself pasting the same instructions a third time, that's when you package it as a skill. Don't write a skill for work you've never done.

4. Write like you're training a new hire.
Clear steps, numbered, with input and output examples. Work that needs fixed results (calculations, file formats) goes into a script instead of being described in words.

5. Test on real data.
Anthropic recommends thorough testing in your own environment before putting important work in Claude's hands.

Using Skills in Claude Code

Claude Code (Anthropic's AI programming tool running on your terminal) is the most flexible place to use skills.

Step 1: Create a skill folder

Personal skills (used in every project):

mkdir -p ~/.claude/skills/summarize-changes

Project skills (only in this repo, committed so the team can use them together) live in .claude/skills/ in the repo.

Step 2: Write SKILL.md

Create a SKILL.md file in the folder you just made, with a clear description like the example above. The !`command` syntax runs a shell command and inserts the result (for example git diff HEAD) into the skill content before Claude reads it.

Step 3: Call a skill

Two ways:

• Automatic: ask naturally, for example "what did I just change?". If it matches the description, Claude uses the skill on its own.
• Manual: type /summarize-changes (can include parameters). Note: only the skill name at the start of the message runs directly; mentioning it in the middle of a sentence just lets Claude consider using it.

Skills from a plugin are called as /plugin-name:skill-name.

Step 4: Manage

• Edit content in the skill folder and changes take effect right away in your session. If you create a new top-level skills folder after starting up, run /reload-skills.
• Use /skill-doctor to see how much context each skill costs and how it's being used.
• Claude Code comes with some built-in skills like /code-review, /debug, /loop, /claude-api.

Lock sensitive skills

For actions with big impact like deploy, put in the frontmatter:

disable-model-invocation: true

Then only you typing /deploy runs it; Claude won't call it on its own. On the flip side, user-invocable: false hides the skill from the menu and only lets Claude use it.

What about old custom slash commands?

Custom commands have been merged into skills. Files in .claude/commands/ still work, but new ones should be written as skills; if names collide, skills take priority.

How do I install Anthropic's built-in skills?

Anthropic's built-in skills are example skills published publicly in the anthropics/skills repository on GitHub, installed into Claude Code via plugins. Anthropic publishes the anthropics/skills repo on GitHub, with example skills (creativity and design, engineering, business communication, office documents), a spec folder describing the standard, and a template folder to start writing your own skills.

In Claude Code, register the repo as a marketplace then install:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

The document-skills package handles Word, PDF, PowerPoint, Excel. Note: according to Agent Skills documentation, the built-in document skills are not included in Claude Code, so you need to install them via plugin like above. The skill groups docx, pdf, pptx, xlsx only publish source code for reference, not open source; many other skills use Apache 2.0.

How do I use skills on Claude.ai and API?

Skills exist in three places, each with its own way to share:

Platform	How to add skills	Scope
Claude Code	Put the folder in ~/.claude/skills/ or .claude/skills/	Per user or per project
Claude.ai	Upload a zip file in Settings → Features	Personal use only
Claude API	Upload via /v1/skills endpoints	Shared across the workspace

A few things to know, according to official docs:

• Custom skills on Claude.ai come with Pro, Max, Team, and Enterprise plans when you turn on code execution.
• Skills don't sync automatically between platforms. A skill you upload to Claude.ai isn't on the API and vice versa; Claude Code uses its own folders. You have to manage each place separately.
• On Claude API, skills run in a sandbox with no Internet and can't install extra packages while running. If you need outside data, provide the data upfront in your request.
• Agent Skills are not covered by the Zero Data Retention agreement and are stored under the standard policy.

Real-world examples for small businesses

Hypothetical example: a 5-person web agency. The team lead keeps noticing members forget the review step before handoff. He creates a project skill in .claude/skills/ with a checklist: run tests, verify environment variables, review mobile interface. The deploy skill is set to disable-model-invocation: true. The skill folder gets committed to the repo, so new hires can clone it and use the same process right away.

Hypothetical example: an accounting office. Every week they receive dozens of PDF files (hypothetical number). The IT person installs document-skills, asking Claude to use the PDF skill to read form fields and then consolidate them into Excel using the xlsx skill. In parallel, the team writes an additional custom skill that describes file naming conventions and data verification rules according to company procedures, testing it on a few sample files before using it in production.

Common theme: skills are not magic, they are just your process written down and saved so AI can follow it consistently.

Safety: treat skills like software

Skills can contain scripts that run on your machine, so don't install them carelessly.

• Only use skills you wrote yourself or from trusted sources like Anthropic.
• With skills from others: open the SKILL.md and any accompanying scripts, check for external network calls before using. Unknown skills could lead to data leaks.
• For actions with major impact (deploy, delete data, send bulk emails), lock them with disable-model-invocation: true.

15-minute checklist for your first skill

1. Pick one task you've given AI instructions for three times or more.
2. Create the folder ~/.claude/skills/skill-name/ and the file SKILL.md.
3. Write a description that says both "what it does" and "when to use it".
4. Write numbered steps, add one example input and output.
5. Open Claude Code, try calling it automatically with a natural question, then try calling /skill-name.
6. Not matching? Fix the description first, only then fix the content.

References

• Agent Skills overview (Anthropic)
• Skills in Claude Code
• Anthropic skill repository on GitHub
• Technical post on Agent Skills

Want to see curated skills by work area (design, content writing, office documents)? Go to the Skills section in AI Tools.