Claude Code Skills: The Complete Practical Guide (2026)

Claude Code skills are folders of instructions — each with a SKILL.md file at the root — that Claude Code discovers automatically and loads only when a task matches the skill's description. Instead of re-typing the same prompt every session or cramming everything into one giant CLAUDE.md, you package a capability once (your migration workflow, your PR review checklist, your test conventions) and Claude pulls it into context exactly when it's relevant.

Anthropic calls these Agent Skills, and they've become the standard unit for packaging agent expertise. This guide covers the whole lifecycle: what Claude Code skills actually are, how SKILL.md and progressive disclosure work, the three places skills can live, how Claude decides to invoke them, and how to share them across a team without copy-paste drift.

What Are Claude Code Skills, and How Do They Differ From Prompts and Rules?

A skill is a directory containing a SKILL.md file — markdown instructions plus a small YAML frontmatter block. What makes skills different from every other way of configuring Claude Code is that they're model-invoked and loaded on demand. Claude scans available skills at session start, reads only their names and descriptions, and pulls in the full instructions when your request matches.

Compare that to the alternatives:

The distinction that matters most in practice: CLAUDE.md is for facts that apply to every interaction ("this is a pnpm monorepo, run tests with pnpm test"), while skills are for procedures that apply to some interactions ("here's our seven-step process for writing a database migration"). Put procedural knowledge in CLAUDE.md and you pay for it in every request; put it in a skill and it costs nothing until the moment it's needed.

You'll also see the term Claude Code agent skills used for the same thing — "agent skills" is the general concept, and Claude Code is the tool with the most mature implementation of it.

Anatomy of a Skill: SKILL.md, Frontmatter, and Progressive Disclosure

A minimal skill is one folder and one file. A realistic skill often carries supporting material:

commit-helper/
├── SKILL.md          # required: frontmatter + instructions
├── reference.md      # optional: detail Claude reads only if needed
└── scripts/
    └── validate.sh   # optional: executable helpers

The SKILL.md itself looks like this:

---
name: commit-helper
description: Generates conventional commit messages from staged changes. Use when the user asks to commit, write a commit message, or clean up git history.
---

# Commit Helper

1. Run `git diff --staged` to inspect the changes.
2. Classify the change: feat, fix, refactor, chore, or docs.
3. Write a one-line summary under 72 characters, imperative mood.
4. If the diff spans multiple concerns, suggest splitting the commit.

Two frontmatter fields do the heavy lifting:

• name — lowercase, hyphen-separated. This is the skill's identifier.
• description — the single most important line in the file. Claude uses it to decide whether the skill applies, so it must say both what the skill does and when to use it.

There are optional fields too; the full field reference and layout conventions are in our SKILL.md format guide.

Progressive disclosure: why skills scale where prompts don't

Skills are cheap because Claude loads them in stages:

1. Metadata only. At session start, Claude sees each skill's name and description — a couple of lines of text per skill.
2. Full instructions. When a request matches a description, Claude reads the entire SKILL.md body into context.
3. Supporting files. Referenced docs, templates, and scripts are opened or executed only if the task actually needs them.

This is why you can have dozens of installed skills without bloating your context window. A 400-line migration runbook with three helper scripts costs you almost nothing on the days you're not writing migrations.

Installing Claude Code Skills: Personal, Project, and Plugin Scopes

Claude Code discovers skills from three places:

Personal skills follow you across every repo on your machine — good for things like your commit style or your preferred debugging process. Project skills live in the repository, so everyone who clones the repo (and every CI agent that runs Claude Code in it) gets the same instructions. Plugin skills arrive as part of a Claude Code plugin, which is how larger toolkits ship skills alongside commands and hooks.

Installing manually is just creating the folder:

mkdir -p .claude/skills/commit-helper
# then write .claude/skills/commit-helper/SKILL.md

That works fine for one skill in one repo. If you're installing published skills — or maintaining the same skill across several repos and several AI tools — a registry CLI does the placement for you:

npm install -g @localskills/cli
localskills login
localskills install acme/commit-helper --target claude

The localskills CLI writes the skill into .claude/skills/ in Claude Code's native format. The same install command can target several tools at once — --target cursor claude windsurf writes .cursor/rules (.mdc) for Cursor, .claude/skills/ for Claude Code, and .windsurf/rules/ for Windsurf, all generated from one published skill. One canonical source, no per-tool forks to keep in sync.

How Claude Decides When to Invoke a Skill

Skills are model-invoked: you don't call them, Claude does. At the start of a session Claude has only each skill's name and description. When your request semantically matches a description, Claude loads that skill and follows it.

This means the description is your trigger mechanism, and vague descriptions are the number one reason skills never fire:

# Too vague — rarely triggers
description: Helps with databases.

# Specific — triggers reliably
description: Writes and reviews Postgres migrations using our Drizzle
  conventions. Use when creating tables, altering schemas, or generating
  migration files.

A few rules that make descriptions trigger well:

• Name the actions users actually ask for. "Use when the user asks to commit, write a commit message, or clean up git history" mirrors real requests.
• Mention concrete nouns: file types, framework names, commands. "Postgres migrations" beats "database work".
• Keep skills distinct. If two skills have overlapping descriptions, Claude may pick the wrong one or neither. Split by task, not by topic.
• State the boundary. "Use when X. Skip when Y" prevents a skill from firing on adjacent tasks it wasn't written for.

You can always invoke a skill explicitly — "use the commit-helper skill" — which is also the fastest way to test a new skill before trusting its description to do the work.

Real Workflows: Claude Code Skills in Day-to-Day Development

The pattern that separates useful skills from shelfware: encode a procedure you'd otherwise explain repeatedly. Some workflows that consistently earn their keep:

Test writing. A skill that documents your fixture setup, mocking rules ("never mock the database layer, use the test container"), and naming conventions. Triggers on "write tests for this" and produces tests that match the suite instead of generic boilerplate.

Database migrations. A checklist skill: naming scheme, how to handle backfills, which operations need a lock warning, plus a scripts/validate.sh that Claude runs before declaring the migration done.

Pre-PR review. A skill encoding your review checklist — security items, error-handling patterns, logging conventions — that you invoke before opening a pull request. It turns "review this" from a generic pass into your team's pass.

Release hygiene. Conventional commit rules, changelog format, version-bump procedure. Small skill, fires constantly, removes a whole category of nitpick comments.

The common thread: each skill is narrow, procedural, and self-contained. The best Claude skills read like a runbook written for a competent new teammate — explicit steps, concrete examples, and commands to verify the result. If you want a full Claude Code skills tutorial that builds one from scratch, follow how to create a Claude skill; for ideas worth installing today, browse the best Claude skills.

Sharing Skills With Your Team

Committing .claude/skills/ to the repo is the right first move — it versions skills with the code and gives every contributor the same setup. But it stops scaling in two situations:

1. Many repos. The same "commit-helper" skill copy-pasted into fifteen repositories drifts within a month. Nobody backports the fix from repo eight.
2. Many tools. Half your team uses Claude Code, the other half Cursor or Windsurf. Now you're hand-maintaining the same instructions in three formats.

A skill registry solves both. On localskills.sh, you publish a skill once and every repo installs it by name; the CLI generates each tool's native format from that single source. Skills are versioned with rollback, so a bad edit isn't a fire drill. Visibility can be public, private, or unlisted, organizations get folders, teams, and member roles for larger libraries, and download analytics show which skills people actually use. If your team prefers reviewing skill changes as pull requests, bidirectional GitHub sync mirrors the whole library to a repo — edits merged there import back as new skill versions automatically.

Skills can also be multi-file packages — docs, scripts, templates — up to 100 MB and 500 files per version, so the runbook-plus-scripts pattern above publishes as a single unit. The full playbook, including rollout order and governance, is in how to share Claude skills with your team.

FAQ: Common Questions About Claude Code Skills

Do Claude Code skills use up my context window?

Barely, until they trigger. Claude loads only each skill's name and description at session start; the full instructions enter context only when a task matches. That's the point of progressive disclosure — installed-but-idle skills are nearly free.

What's the difference between Claude Code skills and MCP servers?

Skills are knowledge: markdown instructions that shape how Claude performs a task. MCP servers are live connections that give Claude new tools — querying a database, calling an API. They compose well: a skill can describe how and when to use tools an MCP server provides. (localskills itself exposes an MCP server so agents can search and install skills over MCP, with OAuth and scoped access.)

Can a skill include scripts and multiple files?

Yes. A skill is a folder, and anything in it — reference docs, templates, shell scripts — is available to Claude on demand. Published skills on localskills.sh support multi-file packages up to 100 MB and 500 files per version.

Why isn't my skill triggering?

Almost always the description. If it's vague ("helps with testing"), Claude can't match requests to it. Rewrite it to name the exact actions and nouns users say, add an explicit "Use when…" clause, and check that no other installed skill has an overlapping description. Invoking the skill by name confirms the skill itself works and isolates the problem to discovery.

Are skills the same as slash commands?

No. Slash commands are user-invoked — you type /command and it runs. Skills are model-invoked — Claude decides to load them based on your request. Commands suit deliberate, repeatable actions; skills suit expertise Claude should apply whenever it's relevant, without you remembering to ask.

---

Ready to stop copy-pasting the same instructions between projects and teammates? Sign up for localskills.sh and publish your first Claude Code skill in minutes.

npm install -g @localskills/cli
localskills login
localskills publish