Installing Skills

Skills are folders. You install one by putting that folder somewhere Claude reads from, then triggering it with a prompt that matches its description. This page covers all four supported surfaces, with troubleshooting at the bottom.

0. Prerequisites

Claude Code: install via npm install -g @anthropic-ai/claude-code or the native installer. Full setup in the Quickstart.
Claude API: the latest Anthropic SDK (anthropic ≥ 0.40 for Python, @anthropic-ai/sdk ≥ 0.27 for Node). Skills require enabling the skills-2025-10-02 beta header.
claude.ai: a Pro, Team, or Enterprise plan. Skills are available on Free for the four official document skills only.
Git: most community skills live in GitHub repos you'll clone.

1. What a skill folder looks like

Every skill is a folder containing at minimum a SKILL.md file with YAML frontmatter:

my-skill/
├── SKILL.md           # required — frontmatter + body
├── scripts/           # optional — executables Claude can call
│   └── run.sh
├── templates/         # optional — files Claude reads/copies
│   └── report.md
└── reference/         # optional — extra docs loaded on demand
    └── api.md

A minimal SKILL.md:

---
name: my-skill
description: Use this skill when the user asks for X. Triggers on phrases like "do X" or "X this file".
allowed-tools:
  - Read
  - Bash
---

# My Skill

When the skill loads, do the following:
1. Read the input file.
2. Run scripts/run.sh with the input.
3. Report back with the result.

The description is everything. Claude decides whether to load your skill based on the description alone — body and bundled files come later via progressive disclosure. Write the description as if it's the only thing Claude will ever see.

2. Claude Code (CLI + IDE)

Claude Code reads skills from two locations, scanned every session:

Scope	Path	When to use
User	`~/.claude/skills/`	Skills you want available across every project (commit-message-writer, security-review).
Project	`.claude/skills/` (in the repo)	Skills specific to one codebase (this repo's deploy script, a local API client).

Install from a Git repo

# 1. clone the source
git clone https://github.com/anthropics/skills.git /tmp/skills-src

# 2. pick a skill, copy it into your user-level skills dir
mkdir -p ~/.claude/skills
cp -r /tmp/skills-src/document-skills/pdf ~/.claude/skills/pdf

# 3. (optional) pin to a specific commit
cd /tmp/skills-src && git rev-parse HEAD > ~/.claude/skills/pdf/.source-commit

# 4. start a fresh session — skill is now discoverable
claude

List installed skills

claude /skills list

Disable a skill without deleting it

# rename the folder so the loader skips it
mv ~/.claude/skills/pdf ~/.claude/skills/_pdf.disabled

Project-level (committed to the repo)

# at the root of your project
mkdir -p .claude/skills
git submodule add https://github.com/your-team/internal-skills .claude/skills/internal
git commit -m "Add internal Claude skills as a submodule"

Tip: Project-scoped skills are checked in to git and shared with the whole team. User-scoped skills are private to you. Prefer project scope for anything teammates would also benefit from.

3. Claude API

The API exposes skills through the Skills container attached to a messages.create call. You need:

The beta header skills-2025-10-02 on every request that uses skills.
A container object listing the skill slugs you want loaded.
For custom skills: upload the folder to the Files API first, then reference the file ID.

Python — using built-in skills

from anthropic import Anthropic

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    betas=["skills-2025-10-02", "code-execution-2025-08-25"],
    container={
        "skills": ["pdf", "xlsx", "docx", "pptx"],
    },
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[{
        "role": "user",
        "content": "Fill out the attached PDF form using this CSV of customer data.",
    }],
)

Node — uploading and using a custom skill

import Anthropic from "@anthropic-ai/sdk";
import fs from "fs";

const client = new Anthropic();

// 1. zip your skill folder, upload via Files API
const file = await client.beta.files.upload({
  file: fs.createReadStream("my-skill.zip"),
  purpose: "skills",
});

// 2. reference it in the container
const resp = await client.beta.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 4096,
  betas: ["skills-2025-10-02"],
  container: { skills: [{ file_id: file.id }] },
  messages: [{ role: "user", content: "Use my custom skill on this input." }],
});

Beta surface. The skills API is in public beta as of 2025-10-02. The beta header name, container shape, and Files API purpose string can change. Pin your SDK version and check the release notes before upgrading.

4. claude.ai (web + desktop)

Open claude.ai and sign in.
Click your avatar → Settings.
Open the Capabilities tab.
Under Skills, toggle the built-in skills you want active: PDF, Word, Excel, PowerPoint, Web Design, etc.
To add a custom skill, click Upload skill, then drag a folder (or .zip) containing a SKILL.md.

Custom skills uploaded to claude.ai are private to your account by default. On Team plans, admins can promote a skill to the workspace so it's available to every member.

From the desktop app

The macOS / Windows desktop apps share settings with the web app — install skills once via the web UI and they'll be available in the desktop client immediately.

5. Via plugins / MCP

Some skills don't ship as standalone folders — they're bundled inside a Claude Code plugin or an MCP server. When you install the plugin / server, the skill becomes available automatically. See the Plugins guide and the MCP guide for the full story.

Install a plugin

# browse the marketplace
claude plugin list

# install one (example: the Playwright plugin, which ships a browser-test skill)
claude plugin install playwright

# the bundled skill is now in ~/.claude/plugins/playwright/skills/

Add an MCP server

# official Postgres MCP, which advertises skills via its instructions
claude mcp add postgres @modelcontextprotocol/server-postgres \
  --env POSTGRES_URL="postgres://localhost/mydb"

# confirm the MCP loaded
claude mcp list

For claude.ai, MCP servers are added via Settings → Connectors. Each connector page lists the skills it bundles.

6. User vs. project scope

Question	Use user scope	Use project scope
Who needs it?	Just me	Anyone working on this repo
Is it codebase-specific?	No	Yes (knows this repo's deploy / DB / API)
Is it sensitive?	Maybe (private API keys)	Should be safe to commit
Path	`~/.claude/skills/`	`.claude/skills/` (in the repo)

If both scopes contain a skill with the same name, the project scope wins. That lets a team override a personal version with the repo's canonical one.

7. Verify a skill is loaded

The fastest sanity check:

claude /skills list

You should see your skill name in the output along with its description. If you don't:

Confirm the folder is in ~/.claude/skills/<skill-name>/ — not nested in a sub-folder.
Confirm SKILL.md exists at the root of the folder (capitalisation matters on Linux).
Run claude --debug and look for skill-loader warnings about malformed frontmatter.
Restart the session — skills are scanned once at startup.

To confirm the skill triggers, type a prompt matching one of its trigger phrases and watch for the skill-load notification in the transcript.

8. Troubleshooting

Symptom	Likely cause	Fix
Skill doesn't show in `/skills list`	Wrong path, missing SKILL.md, or YAML parse error	Check folder location and frontmatter. Run with `--debug`.
Skill is listed but never triggers	Description is too vague; Claude doesn't realise the user's prompt matches	Rewrite the description with concrete trigger phrases. Mention input types, not just outputs.
"Tool not allowed" when skill runs	Skill called a tool not listed in `allowed-tools`	Add the tool to frontmatter, or remove the call from the skill.
API returns `skills_not_enabled`	Missing beta header	Pass `betas=["skills-2025-10-02"]` in your `messages.create` call.
Two skills with the same name	Project scope shadows user scope; both got installed	Rename one. The loader emits a warning when names collide.
Skill bundles a script that won't execute	Missing execute bit on macOS/Linux	`chmod +x ~/.claude/skills/<skill>/scripts/*.sh`

9. Security checklist

Installing a skill is running code. A skill folder can ship scripts that Claude will execute when the skill triggers. Treat third-party skills like any other npm package or shell script you'd install on your laptop.

Read SKILL.md first. See what tools it asks for. Bash and Write are high-trust permissions — make sure the description matches the powers requested.
Inspect bundled scripts. Especially anything in scripts/ or hooks/.
Pin versions. Track the source commit. Don't git pull a skills folder you didn't read.
Prefer official + reputable community sources. anthropics/skills is the canonical starting point.
Sandbox sensitive work. For API calls in production, list only the skills you need in container.skills — don't enable everything.

Next: How skills actually work →

Installing Skills

On this page

0. Prerequisites

1. What a skill folder looks like

2. Claude Code (CLI + IDE)

Install from a Git repo

List installed skills

Disable a skill without deleting it

Project-level (committed to the repo)

3. Claude API

Python — using built-in skills

Node — uploading and using a custom skill

4. claude.ai (web + desktop)

From the desktop app

5. Via plugins / MCP

Install a plugin

Add an MCP server

6. User vs. project scope

7. Verify a skill is loaded

8. Troubleshooting

9. Security checklist