AI engineering

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.

By EpiFive Editorial TeamReviewed/updated 12 min readHow we check articles
On this page

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.

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:

LevelWhen it loadsApproximate cost (per Anthropic)What is loaded
1. MetadataAlways, at startupAbout 100 tokens per Skillname and description from the frontmatter
2. InstructionsWhen a request matches the descriptionUnder 5k tokensThe body of SKILL.md
3. Resources and codeOnly when referencedNone until accessedBundled 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

OptionBest forWhere the text lives
PromptA one-off taskThe chat message
ProjectA body of documents and standing instructions for one subjectThe Project, inside claude.ai
SkillA repeatable procedure you want applied whenever it is relevantA 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:

weekly-status-report/
  SKILL.md

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

---
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:

ScopePathWho gets it
Personal~/.claude/skills/<skill-name>/SKILL.mdAll your projects on this machine
Project.claude/skills/<skill-name>/SKILL.mdEveryone who uses this repository, if you commit it
Nested<subdir>/.claude/skills/<skill-name>/SKILL.mdSessions started in or below that subdirectory
Plugin<plugin>/skills/<skill-name>/SKILL.mdWherever the plugin is enabled

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

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 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

SymptomLikely causeFix
Skill missing from the / menu in Claude CodeThe name contains refused characters such as zero-width spaces, control characters or angle bracketsRename it with plain lowercase letters, numbers and hyphens, then run claude --debug and search the log for [names]
New skills folder not detectedThe top-level directory was created after the session startedRun /reload-skills
Skill in a subdirectory not loadedNested Skills load the first time Claude reads or edits a file thereTouch a file in that directory, or use /add-dir with the path
Fields have no effectA field name is misspelled, so it is ignoredMatch the documented names exactly, for example disable-model-invocation
Upload to claude.ai failsZip too large, folder name differs from skill name, SKILL.md missing, or invalid charactersFix the folder, re-zip and upload again
Skill works in claude.ai but not in Claude Code or the APICustom Skills do not sync across surfacesInstall 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

Questions people ask

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.

ClaudeAgent SkillsClaude CodeSKILL.mdclaude.ai
  1. Automate blog and social media posting with Claude, GitHub Actions and Make

    An architecture for publishing one researched article a day and turning it into a narrated vertical video for YouTube Shorts, Instagram, Facebook and LinkedIn, with the platform limits that shape it.

    AI engineering9 min read
  2. Build Your First MCP Server in Python: Tools, Resources and Testing

    Build a Model Context Protocol server in Python with the official SDK, expose a tool and a resource, test it with MCP Inspector and a Python client, and connect it to VS Code.

    AI engineering9 min read
  3. pgvector on PostgreSQL: Setup, HNSW vs IVFFlat and Tuning

    Set up pgvector on PostgreSQL, create HNSW and IVFFlat indexes, choose between them, tune ef_search and probes, fix filtered queries and confirm index use.

    AI engineering9 min read
  4. Claude Message Batches API: Cut Bulk Job Costs in Python

    Run large asynchronous Claude jobs at 50 percent of standard API prices with the Message Batches API: Python create, poll and results code, limits and fixes.

    AI engineering9 min read
  5. Migrate from the Azure OpenAI Assistants API to Foundry Agent Service

    Move code from the retired Azure OpenAI Assistants API to Foundry Agent Service: assistants to agents, threads to conversations, runs to responses, plus exporting thread history.

    AI engineering10 min read
  6. Getting Started with LLM Evals: A Small-Team Setup with Code

    Build your first LLM eval in an afternoon: write 30 test cases in a JSONL file, grade them with simple code, add an LLM grader for tone, and track the score between prompt changes.

    AI engineering9 min read