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

You have a set of instructions that you paste to AI every week: "write a report according to this template", "review code according to that checklist", "name files according to company rules". Every time you paste is time wasted, and the AI might still get something wrong somewhere.

Skill was created to solve exactly this: turn a repeated set of instructions into a named package, save it once, and have AI pull it out and use it when it encounters the right task.

What is a Skill

Skill (full name is Agent Skill) is a directory containing instructions for Claude to do a specific type of work. The heart of the directory is the SKILL.md file. It can also include scripts, template files, and reference documents.

A skill consists of 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 skill that can run:

---
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. Point out risks: sensitive files, large changes, missing tests.
3. Suggest a commit message.

That's all Claude needs to have a "procedure" to call back anytime.

How Skill differs from prompt, how it differs from MCP

	Prompt	Skill	MCP
What is it	A command you type each time	A saved instructions package that Claude loads when needed	A gateway connecting AI to external tools/data
Use when	One-time work	Repetitive work that needs to be done the same way	Need AI to read/write another system (calendar, CRM, database)
Located at	In the chat	File directory on your machine or account	A connected server

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

How Claude uses a skill

The nice thing about skills is that it doesn't load everything into context right from the start. According to Anthropic's official documentation, skills are loaded in three layers (a "progressive disclosure" mechanism):

1. Metadata (name and description): always loaded, so Claude knows what skills exist.
2. Instructions in SKILL.md: only loaded when your request matches the skill.
3. Reference files and scripts: only loaded or run when actually 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 description, description is the most important part of a skill.

How to write a good skill

1. Description should state both "what to do" and "when to use it".
Claude compares your request to the description to choose a skill. Vague writing means the skill never gets called.

• Weak: Help with reporting.
• Good: Create weekly sales reports from Excel files according to company template. Use when the user asks for weekly reports, sales data summaries, or sending numbers to the director.

2. Follow frontmatter rules.
According to Agent Skills documentation: name maximum 64 characters, lowercase letters, numbers, and hyphens only; description cannot be empty and maximum 1024 characters.

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

4. Write like instructions for someone new to the job.
Clear steps, numbered, with input and output examples. Any work that needs a fixed result (calculations, file formatting) goes into a script rather than being described in words.

5. Test on real data.
Anthropic recommends thorough testing in your environment before handing off important work.

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 directory

Personal skills (use in every project):

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

Project skills (only in this repo, committed so the whole team can use them) go in .claude/skills/ inside the repo.

Step 2: Write SKILL.md

Create a SKILL.md file in the directory 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 the 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 decide whether to use it.

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

Step 4: Manage

• Edit content in the skill directory and it takes effect immediately in your session. If you create a new top-level skills directory after starting, run /reload-skills.
• Use /skill-doctor to see how much context each skill uses 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 this in the frontmatter:

disable-model-invocation: true

Then only you typing /deploy runs it; Claude won't call it on its own. Conversely, 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 there's a name conflict, the skill takes priority.

Install Anthropic's built-in skills

Anthropic released the anthropics/skills repo on GitHub, with sample skills (creative and design, engineering, business communication, office documents), a spec directory describing the standard, and a template directory to start writing your own skills.

In Claude Code, register the repo as a marketplace and 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 release source code for reference, not open source; many other skills use Apache 2.0.

Using skills on Claude.ai and the API

Skills exist in three places, each with its own sharing method:

Platform	How to add skills	Scope
Claude Code	Put directories 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 documentation:

• Custom skills on Claude.ai are available in Pro, Max, Team, and Enterprise plans, when code execution is enabled.
• Skills don't auto-sync between platforms. A skill uploaded to Claude.ai isn't on the API and vice versa; Claude Code uses its own directories. You have to manage each place.
• On Claude API, skills run in a sandbox with no Internet and can't install extra packages at runtime. If you need outside data, provide it upfront in the request.
• Agent Skills are not covered by the Zero Data Retention agreement and are retained under standard policy.

Real-world example for small business

Web agency with 5 people. The team lead notices members often forget to check things before handing off. He creates a project skill in .claude/skills/ with a checklist: run tests, check environment variables, review mobile layout. The deploy skill is set to disable-model-invocation: true. The skill folder is committed to the repo, so anyone who clones it gets the same process right away.

Accounting office. Every week they get dozens of PDF files. The IT person installs document-skills, asks Claude to use the PDF skill to read form fields then compile them into Excel with the xlsx skill. In parallel, the team writes another custom skill describing their file naming rules and data checks per company process, tests it on a few sample files before using it for real.

Common thread: skills aren't magic, they're just your process written down and saved so AI can follow it consistently.

Security: treat skills like software

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

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

15-minute checklist to get your first skill

1. Pick one task you've pasted instructions to AI for three times or more.
2. Create a folder ~/.claude/skills/skill-name/ and a SKILL.md file.
3. Write a description that has 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. Doesn't match? Fix the description first, only then fix the content.

Reference materials

• Agent Skills overview (Anthropic)
• Skills in Claude Code
• Anthropic's skills repository on GitHub
• Technical post on Agent Skills

To see curated skills by work category (design, content writing, office documents), go to the Skill section in AI Tools.