Claude Code Skills (Agent Skills) Guide: Extend Claude with SKILL.md

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. (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.

Custom slash commands are covered in the slash commands reference, including their recent merge into Skills.

A complementary way to extend Claude Code, subagents delegate work to a separate context and pair well with Skills.

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: code.claude.com/docs, code.claude.com)

See also: Learning from skill examples

If you created a skill but Claude Code does not recognize it, walk through the checklist in the skill recognition troubleshooting guide.

Related articles

• Learning from Claude Skill Examples: anthropics/skills Patterns
• Claude Code Skill Not Recognized — Troubleshooting Guide
• Claude Code Installation Guide: native vs npm, Windows Included
• Claude Code settings.json Guide — Permissions, Env Vars & Tools
• Claude Code Pricing Explained (2026): Plans, API Costs & Limits