Skip to main content

Skills: Packaging Expertise Claude Loads on Demand

Claude3 min read
A SKILL.md document with a spark icon representing on-demand expertise

You already know two ways to give Claude guidance: CLAUDE.md (always loaded) and custom slash commands (triggered by you). Skills sit between them. A skill is a packaged bit of expertise — instructions, a workflow, reference material — that Claude loads only when the task calls for it. The result: deep, specialized knowledge available on demand, without bloating every session’s context.

Why not just put everything in CLAUDE.md?#

Because CLAUDE.md is loaded every session and costs context every time. If you only need your detailed "how we write database migrations" guide once a month, paying for it in every session is wasteful. A skill keeps that guide on the shelf; Claude reads its short description always, but pulls the full content into context only when a relevant task appears.

The two kinds of skills#

  • Reference skills — knowledge Claude pulls in when relevant: API docs, a style guide, domain rules, "how we do X here." Claude decides to load it based on the task.
  • Action skills — a workflow you (or Claude) invoke to *do* something: a deploy routine, a code-review checklist, a release-prep sequence. You can trigger these by name like a command.

Both are the same file format under the hood — the difference is how they are used.

Anatomy of a skill: SKILL.md#

A skill is a folder under .claude/skills/ containing a SKILL.md file. The file has YAML frontmatter (metadata, including a crucial description) followed by the instructions. The description is what Claude sees by default — it must clearly say *when* the skill applies, because that is how Claude decides whether to load the rest.

.claude/skills/api-conventions/SKILL.md
---
name: api-conventions
description: How this project designs REST endpoints. Use when adding or changing an API route, controller, or request/response shape.
---

# API conventions

- Routes are versioned under `/api/v1`.
- Use plural nouns: `/users`, not `/user`.
- Validate request bodies with the shared `validate()` middleware.
- Errors use the standard envelope: `{ error: { code, message } }`.
- Every new endpoint needs an integration test in `tests/api/`.

With this in place, when you ask Claude to "add an endpoint for archiving a user," it recognizes the task matches the skill’s description, loads the full conventions, and follows them — without you saying a word about versioning or error envelopes.

Invoking and discovering skills#

Claude loads relevant skills automatically based on their descriptions. For action skills you want to trigger deliberately, you can invoke them by name like a slash command. To see what is available, run /help — skills show up alongside commands. Claude Code also ships with some bundled skills out of the box.

Skills vs. commands vs. memory#

  • Memory (`CLAUDE.md`) — always-on, project-wide rules. Keep it small.
  • Slash command — a prompt you trigger by name; great for short, frequent prompts.
  • Skill — richer, on-demand expertise that loads when relevant; great for detailed guidance you do not want loaded constantly.

A good progression: start by asking in plain English, promote repeated prompts to commands, and graduate detailed domain knowledge into skills as your project grows.

What’s next#

Skills give Claude knowledge on demand. Subagents — next — give it *hands* on demand: separate workers it can delegate to, each with its own focus, running in parallel.

Share: