# What is a Skill? How to create and use Skills so AI does the job right, follows the process

URL: https://opcaios.org/en/blog/skill-la-gi-cach-dung-skill
Date: 2026-10-24
Author: Lê Quốc Nghĩa

What is a Skill? A Skill is a named package of instructions that [Claude](/tien-ich/claude) automatically retrieves and uses when it encounters the right type of work, replacing the instruction text you have to paste in again each week. Imagine sentences like "write a report following this template", "review code using that checklist" or "name files according to company rules": each paste costs time, and AI can still get something wrong. According to Anthropic's Agent Skills documentation (the Claude platform, [Claude Code](/tien-ich/claude-code)), a skill is a directory with `SKILL.md` as its core file; the `name` declaration has a maximum of 64 characters and `description` a maximum of 1024 characters. This post walks through how to create a skill, how Claude loads a skill across 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 has just a few lines.

## What is a Skill?

A Skill (full name *Agent Skill*) is a **directory** containing instructions for Claude to do a specific type of work, according to Anthropic's Agent Skills documentation. The center of the directory is the `SKILL.md` file. It can also include 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 runnable skill:

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

## Current changes

!`git diff HEAD`

## How to do it

1. Summarize the changes in 3-5 bullet points.
2. Point out risks: sensitive files, large changes, missing tests.
3. Suggest one commit message.
```

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

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

Skill differs from prompt in that it's saved in advance and loaded automatically, and differs from MCP in that skill is a process guide, while MCP is a connection to external systems. All three complement each other:

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

How to remember: **prompt is an instruction, skill is a procedure manual, MCP is a hand touching another system.** All three complement each other, they don't replace each other.

## How does Claude use a skill?

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

1. **Metadata** (`name` and `description`): always loaded, so Claude knows what skills exist.
2. **Instructions in `SKILL.md`**: loaded only when your request matches the skill.
3. **Reference files and scripts**: loaded or run only when truly needed. Scripts are run via bash and Claude only receives 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**.

## What makes a good skill write-up?

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

- Weak: `Supports reporting.`
- Good: `Create weekly sales reports from Excel files using company template. Use when user requests a weekly report, consolidates sales figures, or sends data 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 from work you're already repeating.**
When you catch yourself pasting the same instructions for the 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 instructing a newcomer.**
Clear steps, numbered, with input and output examples. Any work that needs fixed output (calculations, file format) goes into a script instead of a written description.

**5. Test with real data.**
Anthropic recommends thorough testing in your own environment before handing over important work.

## Using Skills in Claude Code

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

### Step 1: Create a skill directory

Personal skills (use in every project):

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

Project skills (only in this repo, can be committed for the team to use together) go in `.claude/skills/` within 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 (like `git diff HEAD`) into the skill content before Claude reads it.

### Step 3: Call a skill

There are 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 placed **at the start of the message** runs directly; mentioning the name mid-sentence just lets Claude consider using it.

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

### Step 4: Manage

- Edit content in the skill directory and changes take effect right away in the 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 costs and how often it gets used.
- Claude Code comes with some built-in skills like `/code-review`, `/debug`, `/loop`, `/claude-api`.

### Lock sensitive skills

For actions with major impact like deploy, add to the frontmatter:

```yaml
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 the old custom slash commands?

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

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

Anthropic's built-in skills are sample skills publicly announced in the `anthropics/skills` repository on GitHub, installed into Claude Code through plugins. Anthropic publishes the `anthropics/skills` repo on GitHub, containing 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 repository as a marketplace then install:

```bash
/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 the Agent Skills documentation, the built-in document skills **are not included** in Claude Code, so they need to be installed via plugin as shown above. The skill groups `docx`, `pdf`, `pptx`, `xlsx` only have their source code publicly available for reference, not open source; many other skills use Apache 2.0.

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

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

| Platform | How to add skills | Scope |
|---|---|---|
| Claude Code | Place directory in `~/.claude/skills/` or `.claude/skills/` | Per user or per project |
| Claude.ai | Upload zip file in Settings → Features | Personal use only |
| Claude API | Upload via `/v1/skills` endpoints | Shared across workspace |

A few things to know, per the official docs:

- Custom skills on Claude.ai are available in Pro, Max, Team, and Enterprise plans when code execution is turned on.
- **Skills don't sync automatically between platforms.** Skills uploaded to Claude.ai aren't on the API and vice versa; Claude Code uses its own directories. You have to manage each one separately.
- 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 stored under the standard policy.

## Real-world examples for small businesses

**Hypothetical example: 5-person web agency.** The team lead often notices members forget to run checks before handing over work. He creates a project skill in `.claude/skills/` with a checklist: run tests, check 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 team members clone it and use the same process right away.

**Hypothetical example: accounting office.** Every week they receive dozens of PDF files (hypothetically). The IT person installs `document-skills`, asks Claude to use the PDF skill to read form fields and consolidate them into Excel using the `xlsx` skill. Meanwhile, the team writes an additional custom skill describing file naming rules and data validation according to company procedures, tests it on a few sample files before using it in production.

What they have in common: skills are not magic, they are simply **your processes written down and saved** so AI follows them consistently.

## Safety: treat skills like software

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

- Use only skills you write yourself or from trusted sources like Anthropic.
- With someone else's skill: open `SKILL.md` and any accompanying scripts, check for external network calls before using. Unknown skills can lead to data leaks.
- For high-impact actions (deploy, delete data, send mass emails), lock them with `disable-model-invocation: true`.

## 15-minute checklist to create your first skill

1. Pick **one** task you've given AI instructions for three times or more.
2. Create a folder `~/.claude/skills/skill-name/` and a file `SKILL.md`.
3. Write a `description` that explains "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, then the content.

## References

- [Agent Skills Overview (Anthropic)](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Skills in Claude Code](https://code.claude.com/docs/en/skills)
- [Anthropic's skill repository on GitHub](https://github.com/anthropics/skills)
- [Technical post on Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)

Want to see curated skills by work category (design, content writing, office documents), go to the **Skills** section in [AI Tools](/tien-ich).
