Updated Sep 2026

Claude Skills Ecosystem

One file format, many places to use it. A skill

Claude Skill

A folder with a SKILL.md file that teaches Claude how to do a specific task. Claude loads it automatically when your request matches its description, or you run it directly as `/skill-name`. Skills live in `.claude/skills/<name>/SKILL.md` (project), `~/.claude/skills/` (personal), or inside plugins, and they now also cover what used to be custom slash commands.

"Like a recipe card Claude can reference. When you ask for something matching the recipe's purpose, Claude pulls out the card and follows the instructions."

is a folder with a SKILL.md that teaches Claude how to do one job well. The same idea works in Claude Code, the Claude apps, and the API. Here's how each works and when to reach for it.

Official Documentation

Skills in Claude Code Skills in the API Agent Skills Standard

Where Skills Live

Claude Code

Files in your repo or home folder. Auto-loaded or /typed.

Claude Apps

Upload a zipped skill folder in claude.ai or desktop.

Claude API

Attach skills to Messages API calls in your product.

Plugins

Package skills to share with your team or the world.

1Anatomy of a Skill

A skill is a recipe card. Claude keeps only the card titles (name and description) in mind, and pulls the full recipe out of the drawer when a task calls for it. That's progressive disclosure: you can install dozens of skills without stuffing the context window

Context Window

The amount of text an AI can 'see' at once, measured in tokens: your instructions, the conversation, files it read, and tool results. Current Claude models (Opus 5.5, Sonnet 5, Fable 5.1) offer 1M-token windows and Haiku 4.5 has 200K, but even huge windows work best when kept focused.

"Like short-term memory. The bigger the window, the more the AI can remember from your conversation."

Folder layout

pr-review/
├── SKILL.md        # required: frontmatter + instructions
├── checklist.md    # optional: loaded only if needed
└── scripts/
    └── diff-stats.sh

Name + description are always visible to Claude.

The SKILL.md body loads when the skill is used.

Extra files load only if the instructions point to them.

It follows the open Agent Skills standard, so the same folder can travel between tools.

2Skills in Claude Code

Personal

~/.claude/skills/<name>/SKILL.md

Every project you open.

Project

.claude/skills/<name>/SKILL.md

Commit it; the whole team gets it.

Plugin

<plugin>/skills/<name>/SKILL.md

Runs as /plugin-name:skill-name.

Custom commands are now skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both give you /deploy. Old command files still work, but new ones should be skills: they can hold supporting files and Claude can load them on its own.

Two ways a skill runs

Claude loads it

You say "review this PR", Claude matches the description and pulls the skill in.

You type it

Every skill is also a slash command

Slash Commands

Commands you type in Claude Code starting with `/`: built-ins like /help, /clear, /compact, /context, /resume, /usage, and /init, plus your own. Custom commands have been merged into skills: `.claude/skills/deploy/SKILL.md` and the older `.claude/commands/deploy.md` both create `/deploy`.

"Like keyboard shortcuts, but for conversation. Type a quick command instead of explaining what you want."

: /pr-review, with arguments if you like.

Example: a knowledge skill Claude loads on its own

~/.claude/skills/pr-review/SKILL.md

---
name: pr-review
description: Reviews pull requests and diffs against our checklist. Use when reviewing code, a PR, or a diff.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff *)
---

# PR Review

## Security
- No hardcoded secrets or API keys
- Input validated on the server (Zod)
- Auth checked in the route or server action, not just the UI

## Performance
- No N+1 queries
- Images use next/image

## Output
For each issue: file:line, why it matters, and a suggested fix.
If there is nothing important, say so. Don't invent nitpicks.

Example: a command-style skill only you can trigger

.claude/skills/pre-deploy/SKILL.md

---
name: pre-deploy
description: Pre-deployment sanity check
disable-model-invocation: true
argument-hint: [environment]
allowed-tools: Bash(git status *) Bash(npm run *)
---

# Pre-deploy check for: $ARGUMENTS

Current branch: !`git branch --show-current`
Uncommitted changes: !`git status --short`

1. Run npm run lint and npm run build. Stop on any error.
2. List env vars the code reads that aren't in .env.example.
3. Check for pending database migrations.
4. Report PASS or FAIL with reasons. Do not deploy.

Type /pre-deploy production. The !`command` lines run first and their output is pasted into the skill, so Claude starts with live facts instead of guessing. $ARGUMENTS becomes whatever you typed after the name.

3Frontmatter Cheat Sheet

name	The skill's name, and the /command you type to run it.
description	What it does and when to use it. Claude reads this to decide when to load the skill. Most important line in the file.
when_to_use	Extra trigger guidance, if the description alone isn't enough.
argument-hint / arguments	Hint shown in the / menu, and named arguments you can reference as $name.
disable-model-invocation: true	Only you can run it (by typing /name). Use for anything with side effects: deploy, commit, send.
user-invocable: false	Only Claude can load it. Use for background knowledge that isn't a command.
allowed-tools	Tools Claude may use without asking while the skill runs, e.g. Bash(git status *).
model / effort	Run this skill on a specific model or effort level.
context: fork (+ agent)	Run the skill in its own subagent so its work doesn't fill your main conversation.
paths	Only offer the skill when working on matching files.

Portability: outside Claude Code (claude.ai uploads and the API), only name, description, license, compatibility, metadata, and allowed-tools are accepted. Claude Code-only fields like context or disable-model-invocation make the upload fail, so strip them from skills you plan to share there.

4Skills in the Claude Apps

In claude.ai and the desktop app, Anthropic's built-in skills handle Word, Excel, PowerPoint, and PDF files, and you can add your own by uploading the skill folder as a .zip in your skills settings. Skills there rely on code execution, so make sure it's turned on in your capability settings.

Signed in to Claude Code with the same claude.ai account? Your claude.ai skills can sync into Claude Code too. They show up as /anthropic-skills:<name>. For safety, Claude Code won't run !`command` lines in synced skills; edit synced skills on claude.ai, not locally.

5Skills in the Claude API

Building a product where your users never talk to Claude directly? Attach skills to a Messages API call. Claude runs them inside a code-execution container and can produce real files.

Prebuilt

pptx, xlsx, docx, pdf

Custom

Upload through the /v1/skills endpoints; private to your workspace.

No beta header

Plain client.messages.create with the code execution tool.

Python: generate a spreadsheet with the xlsx skill

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            # your own uploaded skill:
            # {"type": "custom", "skill_id": "skill_01...", "version": "latest"},
        ]
    },
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[{
        "role": "user",
        "content": "Build a monthly budget spreadsheet with a totals row and a chart.",
    }],
)

Files Claude creates come back as file IDs in the code-execution results; download them with the Files API. Mind the cost: code execution plus a big model adds up, so test with small inputs first.

6Sharing and Combining Skills

Share with plugins. Committing .claude/skills/ covers one repo. To share across repos or publicly, package skills into a plugin

Plugin (Claude Code)

An installable bundle that adds skills, subagents, hooks, and MCP servers to Claude Code in one step. A plugin has a `.claude-plugin/plugin.json` manifest; its skills are invoked as `/plugin-name:skill-name`. Install with `/plugin install commit-commands@claude-plugins-official` or browse with `/plugin`.

"Like an expansion pack for a game. One install, and you get new characters, levels, and items together."

(alongside subagents, hooks, and MCP servers) and publish it through a plugin marketplace

Plugin Marketplace

A catalog of Claude Code plugins, usually a Git repository with a `marketplace.json`. The official `claude-plugins-official` marketplace is added automatically; add others with `/plugin marketplace add owner/repo`. Teams use private marketplaces to share their standard skills and hooks.

"Like an app store, except anyone (including your team) can open their own shelf."

. See Claude Code Plugins.

Combine with subagents. A subagent

Subagent

A specialized AI agent Claude Code can delegate a task to. It works in its own separate context window with its own tools and instructions, then reports back a summary. Define one as a Markdown file in `.claude/agents/` (project) or `~/.claude/agents/` (personal) with `name` and `description` frontmatter; Explore, Plan, and general-purpose are built in.

"Like hiring a specialist contractor for a specific part of a project. They work independently and report back when done."

can preload skills with its skills field, so your reviewer always knows your checklists. Or go the other way: give a skill context: fork and it runs inside its own subagent.

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews changed code for security, performance, and team conventions. Use after finishing a feature.
tools: Read, Grep, Glob, Bash
model: sonnet
skills:
  - pr-review
  - team-conventions
---

You are a senior reviewer. Review only the files changed on this branch.
Apply every loaded skill. Report issues by severity with file:line and a fix.

Mental model: subagents are who does the work, skills are what they know, hooks are what always happens, and plugins are the box it all ships in. The decision guide breaks down when to use each.

7Which Flavor Do You Need?

"Improving my own coding workflow?"

→ Personal skill in ~/.claude/skills/

"Enforcing team standards in one repo?"

→ Project skill in .claude/skills/, committed to Git

"A repeatable action with side effects (deploy, release, send)?"

→ Skill with disable-model-invocation: true, so only you trigger it

"Sharing the same setup across many repos or teams?"

→ A plugin

"Non-coders on your team using Claude in the browser?"

→ Upload the skill in the Claude apps

"A feature inside your own product?"

→ API skills via the Messages API

Where skills shine: anything that should come out the same way every time. Commit messages, API response shapes, error copy, SQL conventions, review checklists. One skill, one job, done consistently.

Ready to build your skills?

Step-by-step creation, the decision framework, and how to ship it all as a plugin.

Create Agents & Skills Which One When? Plugins