# What Are Claude Skills? How to Install and Use One Step by Step

> Claude Skills are folders with a SKILL.md file that Claude loads on demand. Learn how they work and how to install one in Claude Code, claude.ai and the API.

Source: https://www.epifive.com/blog/what-are-claude-skills-how-to-install · Published 2026-11-18 · EpiFive

## Key takeaways

- A Skill is a folder with a SKILL.md file; only its name and description are loaded up front, and the body loads when a request matches.
- In Claude Code, personal Skills live in ~/.claude/skills/<skill-name>/SKILL.md and project Skills in .claude/skills/<skill-name>/SKILL.md.
- In claude.ai, you upload a zip under Customize, Skills, and code execution must be enabled first.
- Custom Skills do not sync between claude.ai, the API and Claude Code; each surface needs its own copy.
- Read every file in a third-party Skill before installing it, because Skills can bundle scripts that Claude will run.

A Claude Skill is a folder containing a `SKILL.md` file that teaches Claude a repeatable task, such as how your team writes release notes or fills a specific spreadsheet template. Claude keeps only the Skill's name and description in view, and loads the full instructions when your request matches. To install one, put the folder in `~/.claude/skills/` for Claude Code, or zip it and upload it under Customize, Skills in claude.ai.

## Who this is for and what you will have at the end

This guide is for people who use Claude for the same kind of work repeatedly and are tired of pasting the same instructions into every chat. It also suits developers who use Claude Code and want a shared, version-controlled workflow in a repository. You do not need to write code to follow the claude.ai steps.

By the end you will know what a Skill is and how it differs from a prompt or a Project, how Claude decides to use one, how to create a small working Skill, how to install it in Claude Code and in claude.ai, how to tell whether it triggered, and which safety checks to run before installing a Skill someone else wrote. For the related feature that stores documents and instructions for a team, see [Claude Projects for a team knowledge base](https://www.epifive.com/blog/claude-projects-team-knowledge-base-setup).

## What a Skill is, in plain terms

Anthropic's documentation describes Skills as reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context and best practices. A Skill is a directory. At minimum it holds one file called `SKILL.md`. It can also hold extra Markdown files, scripts and reference material such as templates or schemas.

The difference from a normal prompt is when the text is read. A prompt is conversation-level instruction for one task. A Skill loads on demand, so you write the guidance once and Claude pulls it in only when it is relevant.

### How Claude loads a Skill

Anthropic documents three loading levels, which is why you can install many Skills without filling the context window:

| Level | When it loads | Approximate cost (per Anthropic) | What is loaded |
| --- | --- | --- | --- |
| 1. Metadata | Always, at startup | About 100 tokens per Skill | `name` and `description` from the frontmatter |
| 2. Instructions | When a request matches the description | Under 5k tokens | The body of `SKILL.md` |
| 3. Resources and code | Only when referenced | None until accessed | Bundled files; scripts run and only their output enters context |

The `description` does the matching. Claude compares your request with it, so it has to say both what the Skill does and when to use it. A vague description such as "helps with documents" is the most common reason a Skill never triggers.

### Skills, Projects and plain prompts

| Option | Best for | Where the text lives |
| --- | --- | --- |
| Prompt | A one-off task | The chat message |
| Project | A body of documents and standing instructions for one subject | The Project, inside claude.ai |
| Skill | A repeatable procedure you want applied whenever it is relevant | A folder with `SKILL.md` |

Use a Skill when the thing you keep repeating is a procedure ("when I ask for a weekly status report, use this structure and these checks"), not a pile of reference documents.

## Prerequisites

What you need depends on where you use Claude.

- **Claude Code**: Claude Code installed and a project or home directory you can write to. Custom Skills in Claude Code are filesystem-based and need no upload.
- **claude.ai**: a Pro, Max, Ultra, Team or Enterprise plan with code execution enabled, per Anthropic's documentation for custom Skills. On Team and Enterprise plans, an organization owner must enable code execution and Skills first.
- **Claude API**: the code execution tool, because Skills run in its container.

## Step 1: Write a small Skill

You will create a Skill called `weekly-status-report`. The name rules from Anthropic's overview are: lowercase letters, numbers and hyphens only, a maximum of 64 characters, no XML tags, and the reserved words `anthropic` and `claude` are not allowed. The `description` must be non-empty, at most 1,024 characters, and contain no XML tags.

Create this folder structure:

```text
weekly-status-report/
  SKILL.md
```

Put the following in `SKILL.md`. It is an original example; adjust the sections to your team's format.

```markdown
---
name: weekly-status-report
description: Turns rough notes into a weekly status report with Done, In progress, Blocked and Next week sections. Use when the user asks for a status report, weekly update or progress summary.
---

# Weekly status report

## Instructions

1. Read the notes the user provides.
2. Group items under four headings: Done, In progress, Blocked, Next week.
3. Write each item as one sentence that starts with a verb.
4. Under Blocked, name who or what is needed to unblock each item.
5. If the notes do not say which group an item belongs to, ask instead of guessing.
6. Keep the whole report under 250 words.
```

Keep the body short and specific. Anthropic's Claude Code documentation recommends keeping `SKILL.md` under 500 lines and moving reference material into supporting files that the main file links to.

## Step 2: Install it in Claude Code

Claude Code reads Skills from folders on disk. Anthropic documents these locations:

| Scope | Path | Who gets it |
| --- | --- | --- |
| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All your projects on this machine |
| Project | `.claude/skills/<skill-name>/SKILL.md` | Everyone who uses this repository, if you commit it |
| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | Sessions started in or below that subdirectory |
| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Wherever the plugin is enabled |

To install the example as a personal Skill on macOS or Linux:

```bash
mkdir -p ~/.claude/skills
cp -r weekly-status-report ~/.claude/skills/
ls ~/.claude/skills/weekly-status-report
```

To share it with a team instead, copy it into `.claude/skills/` at the root of the repository and commit it.

### Name collisions

If the same skill name exists at more than one level, Anthropic documents that enterprise overrides personal, and personal overrides project. Plugin Skills use a `/plugin-name:skill-name` form so they do not collide.

### Reloading

Edits to existing skill directories are picked up live. If you created a brand-new top-level skills directory while Claude Code was already running, run `/reload-skills`.

### Using it

You can run a Skill directly by typing its name as a slash command, for example `/weekly-status-report`, optionally followed by arguments. Claude can also load it automatically when your request matches the description. Two frontmatter fields change that behavior:

- `disable-model-invocation: true` stops Claude from loading the Skill on its own. Anthropic suggests it for workflows with side effects, such as deploys.
- `user-invocable: false` hides the Skill from the `/` menu so only Claude uses it, which suits background knowledge.

Claude Code accepts more frontmatter fields than claude.ai, including `allowed-tools`, `argument-hint`, `paths` and `context: fork`. All fields are optional in Claude Code, though `description` is recommended. Field names must match exactly, hyphens included; misspelled fields are silently ignored.

## Step 3: Install it in claude.ai

Custom Skills in claude.ai are uploaded as zip files.

### Turn on code execution

Skills require code execution. On individual plans, open **Settings > Capabilities** and make sure **Code execution and file creation** is on. Anthropic's help article notes that this setting is called **Create and edit files** in the updated Settings layout.

On Team and Enterprise plans, an organization owner opens **Organization settings > Plugins & skills**, selects the **Policy** tab, and makes sure code execution and Skills are enabled. Members then manage their own list under Customize.

### Upload the zip

1. Zip the `weekly-status-report` folder so the folder itself, with `SKILL.md` inside, is what gets zipped.
2. Open **Customize > Skills**.
3. Click the **+** button, then **+ Create skill**.
4. Choose **Upload a skill** and select the zip.
5. The Skill appears in your list. Use its toggle to turn it on or off.

Anthropic's help article lists the usual upload failures: the zip is too large, the folder name does not match the skill name, `SKILL.md` is missing, or the name or description contains invalid characters.

## Step 4: Use it through the API

In the Messages API, you list `skill_ids` in the `container` parameter and include the code execution tool. Anthropic provides pre-built Skills for PowerPoint (`pptx`), Excel (`xlsx`), Word (`docx`) and PDF (`pdf`), and you can upload your own through the `/v1/skills` endpoints. Custom Skills uploaded this way are shared workspace-wide, so every member of the workspace can use them. API Skills run in a sandboxed container with no network access and no runtime package installation.

The full request format is in Anthropic's [Using Agent Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide) guide. Check it before writing code, because the API is versioned and the details change.

## Step 5: Check that it worked

A Skill that is installed but never triggers is a common outcome. Test it in this order.

1. **Ask for the task in plain words.** Type something like "turn these notes into a weekly status report" and paste a few lines. If the Skill loaded, the reply should follow your four headings.
2. **Invoke it by name in Claude Code.** Type `/weekly-status-report`. If it does not appear in the `/` menu, the Skill was not discovered.
3. **Check the first line of the file.** The opening `---` must be the first line of `SKILL.md`. If the YAML does not parse, Claude Code still loads the Skill but with no fields set.
4. **Check the description.** If the Skill exists but does not trigger, rewrite the description to include the words people actually use, such as "status report", "weekly update" and "progress summary".

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Skill missing from the `/` menu in Claude Code | The name contains refused characters such as zero-width spaces, control characters or angle brackets | Rename it with plain lowercase letters, numbers and hyphens, then run `claude --debug` and search the log for `[names]` |
| New skills folder not detected | The top-level directory was created after the session started | Run `/reload-skills` |
| Skill in a subdirectory not loaded | Nested Skills load the first time Claude reads or edits a file there | Touch a file in that directory, or use `/add-dir` with the path |
| Fields have no effect | A field name is misspelled, so it is ignored | Match the documented names exactly, for example `disable-model-invocation` |
| Upload to claude.ai fails | Zip too large, folder name differs from skill name, `SKILL.md` missing, or invalid characters | Fix the folder, re-zip and upload again |
| Skill works in claude.ai but not in Claude Code or the API | Custom Skills do not sync across surfaces | Install it separately on each surface |

## Safety checks before installing someone else's Skill

Community Skills are easy to find on GitHub, and installing one is closer to installing software than to saving a prompt. Anthropic's documentation advises using Skills only from sources you created or obtained from Anthropic, and says that anything else needs a thorough audit.

Before you install a third-party Skill:

- Open every file in the folder, not only `SKILL.md`. Scripts, images and reference files are all part of the Skill.
- Look for network calls, file access outside the task, and commands that do not match the Skill's stated purpose.
- Be cautious with Skills that fetch content from external URLs. Fetched text can carry instructions, and a dependency can change after you reviewed it.
- Prefer Skills with a visible license and an author you can identify, and pin to a specific version or commit where you can.
- Try it first in a throwaway project with no access to sensitive data.

Claude Enterprise organizations can turn on Skill content scanning for custom Skills uploaded in claude.ai, but Anthropic notes that scanning does not cover Skills uploaded through the Skills API or the Console, so review still matters.

## What we checked

- Opened Anthropic's Agent Skills overview on platform.claude.com on 2026-11-18 and confirmed the three loading levels, the `name` limits (64 characters, lowercase letters, numbers and hyphens, reserved words `anthropic` and `claude`) and the `description` limit (1,024 characters).
- Opened the Claude Code Skills documentation on code.claude.com on 2026-11-18 and confirmed the personal, project, nested and plugin paths, the precedence order (enterprise over personal over project), and the `disable-model-invocation` and `user-invocable` fields. The page was long and we read the first 100,000 of its roughly 119,700 characters, so the "Skill not triggering" troubleshooting sections were not read.
- Cross-checked the claude.ai upload path on the Claude Help Center article "Using Skills in Claude" on 2026-11-18: Customize > Skills, the + button, + Create skill, Upload a skill. The overview page and the help article agree that custom Skills need code execution and are uploaded as zip files.
- Cross-checked the plan requirement (Pro, Max, Ultra, Team, Enterprise with code execution enabled) on the overview page. The help article also describes Free among the individual plans for enabling Skills, so the plan list for custom uploads is as stated on the overview page; check your own plan in Settings.
- Checked the example frontmatter against the documented rules: `weekly-status-report` is 20 characters, uses only lowercase letters and hyphens, and does not contain a reserved word. The example description is under 300 characters, well below the 1,024 limit.
- The example Skill in Step 1 is original to this article and is not copied from Anthropic.
- Not tested on a live Claude account, in Claude Code or through the API; steps follow Anthropic's documentation as of 2026-11-18, and menu labels may change.

Last tested: 2026-11-18

## References

- Anthropic, Agent Skills overview: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- Anthropic, Use Skills in Claude Code: https://code.claude.com/docs/en/skills
- Claude Help Center, Using Skills in Claude: https://support.claude.com/en/articles/12512180-using-skills-in-claude
- Anthropic, Using Agent Skills with the API: https://platform.claude.com/docs/en/build-with-claude/skills-guide
- Anthropic, Skill authoring best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- Anthropic open-source skills repository: https://github.com/anthropics/skills

## Frequently asked questions

### What is a Claude Skill?

A Skill is a folder that contains a SKILL.md file with a name, a description and instructions, plus optional scripts and reference files. Claude reads only the name and description at first, and loads the rest when your request matches the description. Anthropic describes Skills as reusable, filesystem-based resources.

### Where do I put a Skill so Claude Code finds it?

Put it in ~/.claude/skills/<skill-name>/SKILL.md for all your projects on one machine, or in .claude/skills/<skill-name>/SKILL.md inside a repository to share it with your team. Claude Code picks up edits to existing skill folders live, but a brand-new top-level skills directory needs /reload-skills.

### How do I upload a custom Skill to claude.ai?

Zip the skill folder, open Customize, then Skills, click the plus button, choose Create skill, then Upload a skill and select the zip. Custom Skills need code execution enabled and a Pro, Max, Ultra, Team or Enterprise plan, per Anthropic's documentation.

### Are Claude Skills safe to install from GitHub?

Treat a Skill like installing software. Anthropic advises using Skills only from sources you trust, and auditing every bundled file, including scripts, before use. A malicious Skill can direct Claude to call tools or run code in ways that do not match its stated purpose.

