TL;DR: A Claude Code skill is a folder with a SKILL.md file — Markdown instructions plus YAML frontmatter — that loads into context only when used, unlike CLAUDE.md, which loads in full every session. Anthropic’s official anthropics/skills repo (180k GitHub stars as of October 9, 2026) installs as a plugin in one command. For any instruction Claude doesn’t need every session, a skill is the cheaper, more reliable home.

What you’ll be able to do after this guide:

• Install Anthropic’s official skills (including mcp-builder and webapp-testing) via the plugin marketplace
• Write a custom skill with dynamic context injection and argument substitution, invocable as /your-skill
• Decide, per instruction, whether it belongs in CLAUDE.md, a skill, a hook, or a subagent — and audit what each one costs you in context

Honest take: Skills are the single highest-leverage Claude Code feature most users haven’t configured. If your CLAUDE.md is over 200 lines, moving the reference material into two or three skills will make Claude follow your remaining rules more consistently — and that migration takes under 30 minutes.

What is a Claude Code Agent Skill?

A skill is a Markdown file (SKILL.md) inside a named folder that teaches Claude Code a reusable workflow or a body of reference knowledge. Claude loads the skill’s one-line description at session start, and the full body only when the skill is actually used — either because you typed /skill-name or because Claude matched your request against the description and loaded it on its own. That on-demand loading is the entire point: a 3,000-word deployment runbook costs you almost nothing until the moment a deploy comes up.

Skills also absorbed an older feature. As of Claude Code 2.1.x, custom slash commands in .claude/commands/ have been merged into skills: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and existing command files keep working. If you wrote custom commands in 2025, you already wrote primitive skills.

Everything in this article was verified on October 9, 2026 against the official docs and the current release:

$ claude --version
2.1.295 (Claude Code)

Where do skill files live?

Six locations, each with a different scope. From the official docs (code.claude.com/docs/en/skills):

Scope	Path	Loads in
Enterprise	.claude/skills/<name>/SKILL.md in managed settings dir	All users, org-deployed machines
Personal	~/.claude/skills/<name>/SKILL.md	All your projects on this machine
Project	.claude/skills/<name>/SKILL.md	This repository (commit it to share)
Nested	<subdir>/.claude/skills/<name>/SKILL.md	Sessions in or below <subdir>
Added directory	.claude/skills/ in a --add-dir path	That session
Plugin	<plugin>/skills/<name>/SKILL.md	Wherever the plugin is enabled, as /plugin-name:skill-name

Name conflicts resolve enterprise over personal, personal over project. Plugin skills are namespaced, so they never collide with your own. Claude Code watches these directories — edits to an existing skill take effect mid-session, but a brand-new top-level skills directory created mid-session needs /reload-skills (more on that gotcha below).

How do you install Anthropic’s official skills?

Anthropic publishes its skills at github.com/anthropics/skills — 180,000 stars and 21,300 forks as of October 9, 2026. Registration is two commands inside a Claude Code session:

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

A second install target, document-skills@anthropic-agent-skills, carries the four document skills (docx, pdf, pptx, xlsx) that power Claude’s own document creation. Worth knowing before you build on them: those four are source-available for reference, not open source, while most of the example skills are Apache 2.0.

The repo holds 19 skills. The ones that matter for a working developer:

Skill	What it does
mcp-builder	Guides Claude through building an MCP server (Python FastMCP or TypeScript SDK) in four phases, ending with a 10-question eval file
webapp-testing	Tests local web apps with Python Playwright scripts; bundles with_server.py to manage server lifecycle
skill-creator	Creates and improves skills, runs with-skill vs without-skill evals, benchmarks pass rate against tokens
frontend-design	Pushes UI work away from “AI default” design — flags cream-and-terracotta palettes, identical card grids
claude-api	API migration and cost-optimization workflows (also ships as a bundled skill in recent Claude Code builds)

The rest skew creative and enterprise (algorithmic-art, brand-guidelines, canvas-design, internal-comms, slack-gif-creator, theme-factory, and so on) — browse before installing, because every model-invocable skill’s description takes a small permanent slice of your context.

One honest caveat from Anthropic’s own README: the repo is for “demonstration and educational purposes,” and behavior can differ between Claude Code, claude.ai, and the API. Test a skill on a throwaway task before wiring it into your release process.

How do you write a custom skill?

Three minutes, start to finish. Create the folder and the file:

mkdir -p ~/.claude/skills/summarize-changes

Then ~/.claude/skills/summarize-changes/SKILL.md (this is the official docs’ own example, and it demonstrates the most useful trick in the format):

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed or wants a commit message.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list
any risks you notice such as missing error handling or hardcoded values.

The !`git diff HEAD` line is dynamic context injection: Claude Code runs the command and inlines its output before Claude reads the skill. Your skill always sees live data, not a stale snapshot. Invoke it directly with /summarize-changes, or just ask “what did I change?” and let the description trigger it.

Every frontmatter field is optional — name defaults to the folder name, and only description is recommended. The fields that change behavior in practice:

Field	Why you’d set it
description + when_to_use	Trigger matching. Truncated at 1,536 characters combined — front-load the key use case
disable-model-invocation: true	Claude can’t auto-run it; only you can, via /name. Use for deploys and anything with side effects
user-invocable: false	Hidden from the / menu; background knowledge only Claude invokes
allowed-tools	Pre-approves tools (e.g. Bash(git add *)) for the invoking turn only
context: fork + agent	Runs the skill in an isolated subagent instead of your main conversation
arguments / $ARGUMENTS	Parameterize: /fix-issue 123 substitutes into the body
model / effort	Per-skill model override or reasoning effort (low to max)

Argument handling is shell-like: $ARGUMENTS takes everything, $0 and $1 take positions, and multi-word values use quotes (/my-skill "hello world" second). You can even stack skills in one message: /write-tests /fix-issue 123.

When should something be a skill instead of CLAUDE.md?

The decision comes down to loading behavior, and getting it wrong costs you twice — once in tokens, once in compliance. CLAUDE.md loads in full into every request. A skill loads its description every request (a sentence or two) and its body only on use. Anthropic’s own guidance: keep CLAUDE.md under 200 lines and move reference material out.

Your situation	Put it in	Why
”Always use pnpm, never npm” — rules for every session	CLAUDE.md	Always-on context is what it’s for
API style guide, schema docs, a deployment runbook	Skill	Loads on demand; near-zero idle cost
Language-specific rules for part of the repo	.claude/rules/ with paths	Loads only when matching files are touched
”Lint after every edit,” “never touch .env”	Hook	Enforcement. A skill or CLAUDE.md line is a request; a PreToolUse hook is a guarantee
Research that reads 40 files	Subagent	Isolation — your main context gets a summary
External systems (DB, Slack, browser)	MCP server	Tools, not instructions — see our MCP server picks

Two of these pairings deserve emphasis. First, skills are not guardrails: Claude interprets a skill, so “never do X” written in one can still be ignored under pressure; a hook fires deterministically. Second, skills and subagents compose — a subagent can preload skills via its skills: field, and a skill with context: fork becomes an isolated worker. Our dynamic workflows guide covers the scaled-up version of that pattern.

If you’ve standardized on a shared AGENTS.md across Cursor, Codex, and Claude Code — covered in our AGENTS.md support breakdown — the same split applies: keep the cross-tool file short and always-on, and push tool-specific runbooks into skills, which the other tools simply won’t load.

What do skills actually cost in context?

Less than any other always-available mechanism, and the costs are now auditable. The loading model, per the official docs:

Feature	What loads at session start	What loads on use
CLAUDE.md	Full content, every request	—
Skill (default)	Name + description only	Full body, once invoked
Skill with disable-model-invocation: true	Nothing	Full body when you invoke it
MCP server	Tool names; schemas deferred	Full schema per tool used
Hook	Nothing (runs externally)	Only what the hook returns

Since v2.1.252, the bundled /skill-doctor command reports each installed skill’s context cost and usage, so “how much is that plugin’s 12 skills costing me per request” has a measurable answer. And since v2.1.283, /doctor prompt-audit audits your instruction files for exactly the bloat this section is about. Run both before and after a migration — the before/after on a long CLAUDE.md is usually the convincing artifact.

Claude Code also ships bundled skills you already have without installing anything: /code-review, /debug, /batch, /loop, /verify, /simplify, /doctor, and /claude-api among them. They’re prompt-based and can be turned off with the disableBundledSkills setting.

What goes wrong in practice?

Two failure modes are easy to hit, and both have one-line fixes.

Creating a skills directory mid-session silently does nothing. Add a first-ever .claude/skills/ folder to a repo while a session is open and the new skill won’t appear in the / menu. Claude Code watches existing skill directories for edits, but a brand-new top-level skills directory isn’t picked up until you run /reload-skills (or start a new session). Edits to already-registered skills, by contrast, apply immediately — the docs call this out, and it’s the first thing to check when a fresh skill seems dead.

The second trap bites when you sync skills to claude.ai: outside Claude Code — claude.ai uploads and the Skills API — only name, description, license, compatibility, metadata, and allowed-tools are accepted in frontmatter, and any other key is a hard error, not a warning. A skill using Claude Code-only fields like context: fork, model, or disable-model-invocation works perfectly in your terminal and then fails upload. If a skill needs to live in both places, keep the portable six fields in frontmatter and express the rest in the body text.

Also worth a line: if Claude keeps not using a skill you expected, the description is almost always the problem — vague or overlapping descriptions lose the matching step. The skill-creator skill (install: /plugin install skill-creator@claude-plugins-official) exists largely to tune descriptions against test prompts, with graded evals.

Verdict: who should set up skills this week?

Anyone whose CLAUDE.md has crossed 200 lines — that’s the clearest signal, and Anthropic’s docs draw the same line. Move reference-shaped content into two or three skills, keep the always-true rules, and both halves work better: rules stop drowning, references stop costing idle tokens.

Your situation	Do this
CLAUDE.md under 100 lines, no repeated workflows	Skip skills for now; you don’t have the problem they solve
Long CLAUDE.md, repeated playbooks pasted into chat	Migrate reference sections to project skills; run /skill-doctor after
Team standardizing Claude Code	Commit .claude/skills/ to the repo; it versions and reviews like code
Building MCP servers or Playwright test flows	Install example-skills@anthropic-agent-skills for mcp-builder and webapp-testing
Need hard guarantees (“never edit .env”)	Not a skill — write a hook

Skills run identically against a local backend, too — a skill is just context, so nothing about the format assumes Anthropic’s API. If you’re running Claude Code against Ollama, skills work unchanged, though smaller local models are noticeably worse at choosing to invoke them from descriptions, so lean on explicit /name invocation there. For picking a local model with enough headroom for agentic work, see runaihome.com’s VRAM-based model guide.

FAQ

Do skills cost extra? No. Skills are a free feature of Claude Code; you pay only the tokens they add to requests. On claude.ai, Anthropic’s example skills are available on paid plans.

Skills vs plugins — what’s the difference? A skill is one capability; a plugin is the packaging that can bundle many skills (plus hooks, subagents, and MCP servers) for distribution. The official repo installs as a plugin marketplace.

Can Claude run a dangerous skill on its own? Only if you let it. disable-model-invocation: true restricts a skill to explicit /name invocation, Skill(deploy *) deny rules block it entirely in /permissions, and allowed-tools grants expire after the invoking turn.

Do skills work in subagents? Yes, differently: skills listed in a subagent’s skills: field are fully preloaded at launch (capped at 32 as of v2.1.295), rather than loaded on demand.

Is there a spec outside Claude Code? The repo ships one under spec/ (the Agent Skills standard), and the same SKILL.md format is accepted by claude.ai and the Skills API — with the six-field frontmatter restriction noted above.

Sources

• Extend Claude Code with skills — official docs
• Extend Claude Code: CLAUDE.md vs skills vs subagents vs hooks — official docs
• How Claude remembers your project — official memory docs
• anthropics/skills — official Agent Skills repository
• Claude Code CHANGELOG (v2.1.295) — anthropics/claude-code

Last updated October 9, 2026. All version numbers, commands, and file paths verified against Claude Code 2.1.295 and the official documentation on the day of writing; skills behavior changes frequently between minor versions.

Know which coding tool is worth paying for

Hands-on comparisons of AI coding assistants and what each one costs to run — including the local-model path. Sent only when something changes. Unsubscribe anytime.

Email address Subscribe