Claude Code Skills (Agent Skills) let you package a recurring workflow or expertise so Claude can "pull it out and use it when needed." This guide covers what skills are, how to build one with SKILL.md, and where to put it. (As of June 2026. Details may change, so check the official docs for the latest.)
What a skill is
A skill is a modular capability that extends Claude's functionality. Each skill packages instructions, metadata, and optional resources (scripts, templates). Claude uses a skill automatically when it judges the task is relevant. A key design is dynamic loading — normally only the list of skills is kept light, and the content of a relevant skill is loaded into context only when needed. So even with many skills, the context doesn't get unnecessarily heavy.
SKILL.md structure
A skill is defined by a SKILL.md file, made of YAML frontmatter + a Markdown body. The description in the frontmatter determines when Claude invokes the skill, so write it specifically and with relevant keywords.
.claude/skills/summarize-changes/SKILL.md
---
name: summarize-changes
description: Summarize uncommitted changes in the git working tree and flag risky ones
---
# Summarize changes
1. Read the diff in the current working tree.
2. Summarize the changes in human-readable form.
3. Flag anything that looks risky.Above is an example skill that summarizes git changes. Skills are stored per folder, and the folder name is the skill name. The body describes, in natural language, the steps Claude should follow.
Where to put it — four sources
Claude Code scans several locations to build the list of available skills.
- Personal (global):
~/.claude/skills/<name>/SKILL.md— skills used across all your projects. - Project:
.claude/skills/<name>/SKILL.md— skills scoped to a specific repository (shareable with your team). - Plugin: skills bundled with an installed Claude Code plugin.
- Built-in: skills available in every session (e.g.
/code-review,/batch,/debug,/loop,/claude-api).
Automatic vs direct invocation
Skills work two ways: (1) Claude reads the description and loads the skill automatically when relevant, or (2) you invoke it directly via a slash command (e.g. /summarize-changes). The frontmatter lets you control who (you or Claude) invokes it.
Note: custom slash 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, and existing commands/ files keep working. Skills add features on top: a directory for supporting files, invocation-control frontmatter, and automatic loading.
Define once, use in many places
Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Per the official docs, Claude on the web (claude.ai) and the Claude Desktop app also support skills, so a skill you define once can be shared across environments. (Claude Code extends the standard with extra features like invocation control, subagent execution, and dynamic context injection.)
Summary
Key points: (1) a skill is a modular capability of instructions and resources, loaded automatically when relevant; (2) it's defined by SKILL.md (YAML frontmatter + body), with description deciding when it's invoked; (3) it loads from four sources — personal, project, plugin, and built-in; (4) being an open standard, it's shareable across tools. For authoring and best practices, see the official Claude Code skills docs.
For where to get useful skills, see the Claude skills library.
This article is an introductory explanation based on Claude/Claude Code official documentation. Paths, commands, and features may be updated, so verify the latest spec in the official docs before use. (Official sources: docs.claude.com, code.claude.com)