title: "What is a Claude Code Skill?" description: "A Claude Code skill is a SKILL.md file that adds a named, triggerable capability to Claude Code. Learn what skills are and how they differ from prompts." pubDate: "2026-04-13" category: skills tags: ["claude-code-skills", "foundations", "beginner"] cluster: 1 cluster_name: "Foundations & Getting Started" difficulty: beginner source_question: "What is a Claude Code skill?" source_ref: "1.Beginner.1" word_count: 1460 status: draft reviewed: false schema_types: ["Article", "FAQPage"]

What is a Claude Code Skill?

Quick answer: A Claude Code skill is a SKILL.md file installed in your .claude/skills/ directory that adds a named, reusable capability to Claude Code. When triggered by name or matching natural language, Claude loads the file and follows the defined process to produce a specified output. Skills are the difference between instructing Claude once and instructing it every session.

How is a Claude Code skill different from a regular prompt?

A regular prompt is text you type into Claude at the start of a session. A skill is a structured SKILL.md file that Claude loads automatically from your .claude/skills/ directory when the task matches, without any manual input. The distinction is not cosmetic — it changes the economics of working with Claude entirely.

When you use a prompt, you write or paste instructions at the start of each relevant session. When you use a skill, Claude activates it from your .claude/skills/ directory without any manual input. The skill's process steps, output format constraints, and rules all apply consistently from the moment it triggers.

A prompt dies at the end of a session. A skill persists across every session, every team member, and every model version you use. In a typical development week, developers re-enter the same project context into Claude 6 to 8 times (AEM production analysis, 2026). A skill brings that count to zero.

There are over 700,000 skills in the Claude Code community (Claude Code ecosystem data, 2026). Most of them are prompts with a file extension, they trigger sometimes, follow inconsistent paths, and produce different output on Tuesday than on Wednesday. A real skill is built differently.

"Each skill only takes up a few dozen extra tokens, with the full details only loaded in should the user request a task that the skill can help solve." — Simon Willison, developer and data journalist (October 2025, https://simonwillison.net/2025/Oct/16/claude-skills/)

What are the four core components of a working Claude Code skill?

A Claude Code skill that works reliably in production has four components: a trigger description, a defined process, an output contract, and a test suite. All four are required. A skill missing any one of them is a fair-weather skill — functional when conditions are ideal, unreliable everywhere else.

1. A trigger description. A single-line description in the SKILL.md frontmatter that tells Claude when to activate the skill. The description controls whether the skill fires on the right input and stays silent on the wrong one. The character limit is 1,024 (Claude Code specification, 2026).

2. A defined process. Numbered steps in the SKILL.md body that tell Claude what to do, in what order, using which tools. Unnumbered lists are suggestions. Numbered lists are instructions. The distinction produces measurably different adherence rates in production skill use.

3. An output contract. A specification of exactly what the skill produces and what it explicitly does NOT produce. Without an output contract, Claude decides what to include. The output varies across runs. Downstream processes that depend on consistent structure break.

4. A test suite. At least 5 test inputs, including edge cases, that verify the skill produces correct output without instruction edits. A skill that passes 4 inputs and fails on the 5th is not production-ready, it is a skill waiting for the right moment to break.

Where does a Claude Code skill live and how does Claude find it?

A Claude Code skill lives in a named subdirectory under .claude/skills/ — either at project level (.claude/skills/skill-name/SKILL.md, relative to your project root) or at user level (~/.claude/skills/skill-name/SKILL.md, in your home directory). Claude Code scans both locations at startup and loads each skill's metadata into its active context automatically.

  • Project level: .claude/skills/[skill-name]/SKILL.md (relative to your project root)
  • User level: ~/.claude/skills/[skill-name]/SKILL.md (in your home directory)

Each skill gets its own named subdirectory. A file at .claude/skills/SKILL.md without a subdirectory is invisible to the discovery system. The subdirectory name becomes part of how the skill is identified and invoked.

At startup, Claude Code loads the metadata (frontmatter) from every SKILL.md it finds. Each skill adds approximately 100 tokens of overhead (Claude Code specification, 2026). The system prompt budget for skill discovery is 15,000 characters total (Claude Code specification, 2026). At 40 or more active skills, this budget starts to constrain discovery accuracy.

Project-level skills take precedence over user-level skills when names conflict. Team-shared skills in .claude/skills/ override individual skills in ~/.claude/skills/ within that project.

When should I use a skill instead of just typing instructions?

Use a skill when the task repeats across sessions, when the output must be consistent for a downstream process, or when multiple team members need the same capability. If any of those three conditions apply, a skill will outperform typed instructions every time — it fires automatically, enforces your format, and scales across your team.

Use a skill when you meet any of these three conditions:

The task repeats. If you are giving Claude the same instructions across multiple sessions or for multiple team members, those instructions belong in a skill. The skill fires automatically. The instructions do not need to be typed or pasted.

The output must be consistent. If the format of Claude's output matters downstream, for a pipeline, a template, a review process, a skill enforces that format every time. Ad-hoc instructions produce ad-hoc output.

Multiple people need the same capability. A skill installed at the project level is available to every team member who opens the project in Claude Code. Instructions in a chat are available to one person, once. Skills scale. Instructions do not.

One pattern worth naming: if you have explained the same context to Claude 3 or more times in the past week, that context belongs in a skill. "3 or more repetitions" is the threshold AEM skill engineers use before recommending skill creation to a client team (AEM engineering practice, 2026).

This pattern works for single-domain, well-scoped tasks. For complex orchestration workflows that need to coordinate multiple distinct capabilities in sequence, skills are one component of the architecture, not the entire architecture.

What does a simple Claude Code skill look like?

A working Claude Code skill is a SKILL.md file with a frontmatter trigger description, a numbered process in the body, and an explicit output contract stating what the skill produces and what it does not. The example below is the minimum viable version for a commit message generator — functional, triggerable, and testable.

The minimum viable SKILL.md for a commit message generator:

---
name: commit-message
description: "Use this skill when the user wants to create a git commit message. Do NOT use for PR descriptions or changelogs."
---

## What this skill does
Generates a Conventional Commits-format commit message from staged changes.

## Process

Step 1: Use the Bash tool to run `git diff --staged`. Read the output.
Step 2: Identify the change type (feat, fix, refactor, docs, chore) from the diff.
Step 3: Output a commit message in this exact format:
  - Line 1: `type(scope): short description under 72 characters`
  - Line 2: blank
  - Line 3+: body describing what changed and why (optional, include if the change needs context)

## Output contract
Produces: a git commit message, nothing else.
Does NOT produce: PR descriptions, issue references, or suggested next steps.

That skill has a trigger description, a 3-step process, named tools, and an explicit output contract. It does not cover every edge case, malformed diffs, binary files, merge commits, but it is a starting point you can test and harden.

For a step-by-step walkthrough of building your first skill from scratch, see How do I create my first Claude Code skill?.

For the complete reference on SKILL.md file structure, see What goes in a SKILL.md file?.

For the full guide covering all four skill components and the production testing bar, see The Complete Guide to Building Claude Code Skills in 2026.

Frequently Asked Questions

How many Claude Code skills should I have in one project?

Between 10 and 30 active skills per project is the practical range. Below 10, most repetitive tasks still require manual instruction. Above 30, description overlap creates trigger conflicts and the 15,000-character discovery budget starts constraining selection accuracy. Archive skills unused in the last 90 days rather than leaving them active in the library.

Can I use Claude Code skills without a paid subscription?

Claude Code has a free tier with usage limits. The SKILL.md format itself is open, you can write and test skill files on any tier. Whether specific model capabilities work as expected depends on your account level. Skills designed for Opus produce different (often degraded) output on Haiku for tasks requiring multi-step reasoning.

What's the simplest possible Claude Code skill I can build in 5 minutes?

Create .claude/skills/quick-summary/SKILL.md with frontmatter containing name and description fields, and a body with one process step. That is a functional skill. It will not pass production testing on edge cases, but it will trigger reliably and follow a defined process, which puts it ahead of a prompt you type each session.

Do Claude Code skills work in VS Code or only in the terminal?

Skills work in:

  • The Claude Code CLI
  • The VS Code extension
  • The JetBrains extension
  • The Claude desktop app

The skill system runs at the Claude Code layer, not the interface layer. Any Claude Code installation reads SKILL.md files from the .claude/skills/ directory automatically at startup.

Can I use Claude Code skills in the Claude desktop app?

Yes. The Claude desktop app runs Claude Code under the hood. Skills installed in .claude/skills/ at the project level, or in ~/.claude/skills/ at the user level, load in the desktop app the same way they load in the CLI. The interface is different; the skill system is the same.

Last updated: 2026-04-13