What Are Claude Skills? The Complete Guide

Claude Skills are the answer to a problem every heavy Claude user hits: you keep re-explaining the same procedure. How your team writes migrations. The exact steps of your release checklist. The way you want commit messages formatted. A skill packages that procedure once — as a folder with a SKILL.md file — and Claude loads it by itself whenever the task calls for it.

The anatomy of a skill

A skill is a directory containing one required file:

.claude/skills/conventional-commits/
└── SKILL.md

And SKILL.md is YAML frontmatter plus Markdown instructions:

---
name: conventional-commits
description: Generate clear Conventional Commits messages from staged changes.
  Use when committing code and you want a well-structured, consistent message.
---
 
1. Run `git diff --staged` to see what's actually being committed.
2. Pick the type (feat, fix, refactor, docs, chore) from the dominant change.
3. Write `type(scope): summary` under 72 characters, imperative mood.
4. Add a body only if the "why" isn't obvious from the summary.

That's the entire format. No build step, no manifest, no registration call. The frontmatter's description decides when the skill activates; the body is what Claude does once it has. Optional extras — scripts, templates, reference docs — sit in the same folder and are referenced by relative path. The full field list (there are more than most posts document, including context: fork for running a skill in an isolated subagent) is in our SKILL.md reference.

Progressive disclosure: why skills are cheap

The design insight that makes skills work is that they load in three stages:

Twenty installed skills cost roughly a screenful of text at rest. Compare that with stuffing the same twenty procedures into CLAUDE.md, where every word is paid for in every session, relevant or not. Skills are the overflow valve that keeps project memory small.

How a skill gets invoked

Three paths:

1. Automatic — Claude reads every installed skill's name and description at startup. When your request matches one ("commit this" → the commit skill), it loads the body and follows it. This is why the description is the single most important line you'll write: it's the routing signal.
2. Explicit — type /skill-name (with optional arguments) to force it, bypassing description matching entirely.
3. The Skill tool — Claude can programmatically select and run a skill mid-task, the same way it invokes any other tool.

Skills also take arguments — /release-notes v2.3 — exposed to the body via $ARGUMENTS and positional or named variables. And you can flip the defaults per skill: disable-model-invocation: true makes a skill manual-only (right for deploy runbooks), while user-invocable: false hides it from the / menu and leaves it as background knowledge Claude applies on its own.

Where skills run

This is what changed in the last year: skills stopped being a Claude Code feature and became a portable format.

• Claude Code — the native home: personal skills in ~/.claude/skills/, project skills in .claude/skills/, plus plugin-distributed and enterprise-managed skills.
• claude.ai — upload a skill as a ZIP (Settings → Capabilities to enable code execution first). Anthropic's document skills — Word, Excel, PowerPoint, PDF — are pre-built and always active there.
• The Claude API — upload custom skills to the /v1/skills endpoint and attach them to a Messages request through the code-execution container. Details and code in Skills on claude.ai and the API.
• The Agent SDK — skills load from the same .claude/skills/ directories when you build your own agents.
• Everywhere else — in December 2025 Anthropic published Agent Skills as an open standard at agentskills.io. GitHub Copilot, Cursor, VS Code, Gemini CLI, and dozens of other tools now read the same SKILL.md format. A skill you write for Claude Code is no longer locked to it.

One caveat worth knowing: surfaces don't sync. A skill uploaded to claude.ai doesn't appear in Claude Code or the API — each surface gets its own copy.

Skills vs. commands, subagents, and MCP

The extension points overlap less than they look like they do:

The longer decision-table treatment is in Skills vs. Agents vs. Commands.

Getting skills

Three routes, in increasing order of effort:

1. Install ready-made ones. The AgentsCamp skills library has 90+ across git, testing, databases, performance, and security — each page shows the full SKILL.md with an install path, or use npx agentscamp add skills/<name> from the terminal. Our picks for 2026 are the short list. Anthropic's own examples live in the public anthropics/skills repo on GitHub.
2. Study the patterns. Annotated examples walks through five SKILL.md shapes — minimal, scoped-tools, bundled-script — with the reasoning per line.
3. Write your own. The third time you type the same instructions, that's a skill. Writing Your First Skill is the step-by-step; best practices covers the craft of descriptions that trigger reliably.