What Are Claude Code Skills? Guide & How to Build One

A Claude Code Skill is a folder containing a SKILL.md file that Claude loads on demand — Anthropic calls Agent Skills "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks." You write the instructions once; Claude reads the one-line description at startup, then loads the full body only when your request matches. This guide covers what a Skill actually is, how it differs from MCP servers and slash commands (they are now the same mechanism), a minimal SKILL.md you can copy, where each Skill lives on disk, and which repos are worth trusting — as of July 2026, with every specific claim tied to an Anthropic doc or the real GitHub repo.

What a Claude Code Skill is

A Skill is a folder with a SKILL.md file that Claude Code loads on demand to do a specific task better. Anthropic's canonical definition: Agent Skills are "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks." In Claude Code's own words, "you create a SKILL.md file with instructions and Claude adds it to its toolkit. Claude uses skills when relevant, or you invoke one directly with /skill-name."

The mental model that makes everything else click: Claude reads only the Skill's short description at startup (roughly 100 tokens), and pulls in the full instructions only when your request matches. It is a reference book on the shelf, not a paragraph stapled to every prompt. That on-demand loading — Anthropic calls it progressive disclosure — is what lets you install dozens of Skills without bloating context. If you are new to the CLI itself, start with our how to use Claude Code guide, then come back here.

Anatomy of a SKILL.md

Every Skill requires one file — SKILL.md — with a YAML frontmatter block between --- markers, followed by markdown instructions. Two surfaces define the rules slightly differently, and it matters which one you are targeting:

• The platform / API spec lists name and description as required, with hard limits: name is max 64 characters, lowercase letters, numbers and hyphens only, no XML tags, and cannot contain the reserved words "anthropic" or "claude"; description must be non-empty, max 1024 characters, no XML tags.
• In Claude Code specifically, all frontmatter fields are optional and only description is recommended. Omit name and it defaults to the directory name; omit description and Claude uses the first paragraph of the markdown body.

Beyond the single file, a Skill can bundle three optional subdirectories, each with a defined role:

Skill vs MCP vs slash command

Skills and slash commands are now the same mechanism; MCP is a different, complementary thing. This is the comparison people actually search for, so here it is straight:

Two clarifications the fact sheet is explicit about:

• Slash commands = Skills. "Custom commands have been merged into skills." A file at .claude/commands/deploy.md and a Skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Old .claude/commands/ files keep working; if a Skill and command share a name, the Skill wins.
• MCP is complementary, not replaced. Anthropic: "Skills can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows that involve external tools and software." A Skill can even include code Claude runs as a tool via bash — distinct from MCP's tool integration. Rule of thumb: encode a workflow in a Skill; connect a system with MCP. If you are wiring MCP-style thinking loops, our sequential thinking in Claude Code guide pairs well here.

Build a minimal Skill

The smallest working Skill is one folder and one file. Create the directory, drop in a SKILL.md, and Claude Code picks it up — no install step, no restart if the .claude/skills/ folder already existed at session start.

# project-scoped: this repo only
mkdir -p .claude/skills/summarize-changes
$EDITOR .claude/skills/summarize-changes/SKILL.md

A minimal SKILL.md — frontmatter plus instructions. In Claude Code you could drop name entirely (it defaults to the folder summarize-changes), but including it and a sharp description is good practice because the description is what Claude matches on:

---
name: summarize-changes
description: Summarize the current git diff into a short, reviewable
  changelog grouped by area. Use when the user asks to summarize changes,
  write a changelog, or explain what changed before a commit.
---

# Summarize changes

Run `git diff --staged` (fall back to `git diff` if nothing is staged)
and produce:

1. A one-line summary of the overall change.
2. Bullets grouped by area (api, ui, tests, docs), most impactful first.
3. A short "risk" note for anything that touches auth, migrations, or
   money paths.

Keep it under 200 words. Do not invent changes that are not in the diff.

That is a complete, valid Skill. Now typing /summarize-changes invokes it, and Claude will also reach for it on its own when you ask something like "write me a changelog for what I just staged." To grow it: add a references/changelog-style.md for house conventions, or a scripts/diffstat.sh Claude can run via bash without reading the script into context. Anthropic recommends keeping SKILL.md under 500 lines and pushing detailed reference material into separate files.

Where Skills live and how to install

A Skill's location decides its scope; installing one is usually just putting the folder in the right place. The four storage locations in Claude Code:

When two Skills share a name across levels, precedence is enterprise > personal > project, and any of those overrides a bundled Skill of the same name. Plugin Skills use a plugin-name:skill-name namespace, so they can never collide.

A few operational details worth knowing:

• Live reload. Adding, editing, or removing a Skill under ~/.claude/skills/, the project .claude/skills/, or a .claude/skills/ inside an --add-dir directory takes effect within the current session. Only creating a top-level skills/ directory that did not exist at session start needs a restart.
• Monorepo discovery. Project Skills load from .claude/skills/ in the starting directory and every parent up to the repo root; Claude Code also discovers nested .claude/skills/ directories on demand as you work in subfolders.
• Plugin marketplaces. Some third-party collections install as plugins. BuilderIO's repo, for example, uses /plugin marketplace add BuilderIO/skills then /plugin install builder-skills@builder-skills (more in the repos section).

Invoking, arguments & control

You invoke a Skill by typing / plus its directory name, or Claude auto-loads it when your request matches the description. Note the subtlety: the command name comes from the Skill's directory name — the frontmatter name is only the display label (the one exception is a plugin-root SKILL.md).

Skills accept arguments, which is what makes them feel like commands:

• $ARGUMENTS — all args as one string. Running /fix-issue 123 replaces $ARGUMENTS with 123.
• $ARGUMENTS[N] or $N — 0-based positional args.
• $name — named args you declare in an arguments frontmatter block.

Two more Claude-Code-specific levers control who can invoke a Skill (by default, both you and Claude can):

• disable-model-invocation: true — only the user can invoke it; Claude will not auto-trigger.
• user-invocable: false — only Claude can invoke it; hidden from the / menu.

There is also dynamic context injection: a !`<command>` line runs a shell command before the Skill content reaches Claude, and its output replaces the placeholder (multi-line uses a fenced ```! block). Important framing — this is preprocessing done by Claude Code, not something Claude decides to execute. These invocation-control and context-injection features are Claude Code's extensions to the open standard, described next.

Progressive disclosure & context cost

Skills are cheap on context because they load in three levels. This is the design that lets you keep many Skills installed without paying for all of them on every turn:

Concretely: Level 1 metadata (name + description) is always loaded at startup at ~100 tokens per Skill; Level 2 (the SKILL.md body) loads only when the Skill triggers and stays under ~5k tokens; Level 3+ resources load as needed and are effectively unlimited because scripts run via bash without loading their contents into context. One lifecycle detail: when a Skill is invoked, the rendered SKILL.md enters the conversation as a single message and stays for the rest of the session — Claude Code does not re-read the file on later turns, which is another reason to keep it tight.

Claude Code Skills follow the Agent Skills open standard (agentskills.io), which works across multiple AI tools; Claude Code extends it with the invocation control, subagent execution (context: fork), and dynamic context injection covered above. It also ships bundled Skills in every session unless disabled with disableBundledSkills — including /code-review, /batch, /debug, /loop, and /claude-api. These are prompt-based (they instruct Claude rather than executing fixed logic) and invoked like any other Skill.

Where to find good Skills

Start with Anthropic's own repos, then vet third-party ones like software. As of July 2026, dozens of Skill repos exist; these three are load-bearing and verifiable:

• anthropics/skills — Anthropic's official public repo. Contains ./skills (example Skills by category), ./spec (the Agent Skills standard), and ./template (a skill template). Provided for demonstration/educational purposes; most are Apache 2.0, while the document Skills (docx, pdf, pptx, xlsx) are source-available.
• anthropics/launch-your-agent — an official Anthropic repo of Skills that take a founder from idea to a live Claude Managed Agent. Its Skills live in .claude/skills/ and are picked up automatically when you run Claude Code inside the folder — nothing to install.
• BuilderIO/skills — a third-party, MIT-licensed collection ("small, composable skills for coding agents") that doubles as a Claude Code plugin marketplace. Install: /plugin marketplace add BuilderIO/skills, then /plugin install builder-skills@builder-skills; update with /plugin marketplace update builder-skills. It provides Skills including /visual-plan, /visual-recap, /agent-watchdog, /plan-arbiter, /plow-ahead, and /read-the-damn-docs. This is one project's approach, not an Anthropic standard.

To build and evaluate your own, the official skill-creator plugin (from claude-plugins-official) automates the process — install with /plugin install skill-creator@claude-plugins-official, run /reload-plugins, and it runs A/B baseline comparisons (with-Skill vs disabled) recording pass rate, tokens, and duration.

FAQ