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:
| 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:
weekly-status-report/
SKILL.mdPut 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:
| 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:
mkdir -p ~/.claude/skills
cp -r weekly-status-report ~/.claude/skills/
ls ~/.claude/skills/weekly-status-reportTo 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: truestops Claude from loading the Skill on its own. Anthropic suggests it for workflows with side effects, such as deploys.user-invocable: falsehides 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
- Zip the
weekly-status-reportfolder so the folder itself, withSKILL.mdinside, is what gets zipped. - Open Customize > Skills.
- Click the + button, then + Create skill.
- Choose Upload a skill and select the zip.
- 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.
- 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.
- Invoke it by name in Claude Code. Type
/weekly-status-report. If it does not appear in the/menu, the Skill was not discovered. - Check the first line of the file. The opening
---must be the first line ofSKILL.md. If the YAML does not parse, Claude Code still loads the Skill but with no fields set. - 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
namelimits (64 characters, lowercase letters, numbers and hyphens, reserved wordsanthropicandclaude) and thedescriptionlimit (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-invocationanduser-invocablefields. 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-reportis 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
Comments
Questions and tips are welcome. Comments are checked by the EpiFive team before they appear; please do not share passwords, phone numbers or other private details.