Skills

Skills

Sep 5, 2026

Package reusable Claude Code workflows, commands, instructions, scripts, and references that load only when needed.

What Skills Are

Skills are modular capability packages. A skill can contain instructions, command prompts, scripts, references, templates, and other supporting files. Claude Code discovers skill metadata up front, then loads the full skill only when the current task matches its description.

Think of skills as "context on demand." They keep CLAUDE.md short while still giving Claude rich procedures for work you repeat.

What Belongs in a Skill

Use a skill for:

A workflow that repeats across projects.
A domain playbook that is too long for CLAUDE.md.
A custom slash command with supporting context.
A review checklist, migration process, release process, or debugging flow.
Templates, scripts, or references that should travel with the instructions.

Do not use a skill for one-off project facts. Put those in CLAUDE.md or .claude/rules/.

Skill Structure

Each skill lives in a directory with SKILL.md at the root:

skill layout

.claude/skills/
└── database-migration/
  ├── SKILL.md
  ├── references/
  │   └── migration-checklist.md
  └── scripts/
      └── verify-migration.sh

The frontmatter is the discovery layer:

SKILL.md

---
name: database-migration
description: Use when creating, reviewing, or verifying database migrations.
---

# Database Migration

1. Inspect the current schema and existing migrations.
2. Create the smallest incremental migration.
3. Regenerate types if the project requires it.
4. Run the migration verifier script.
5. Summarize data-loss risk and rollback notes.

The description should be written as a trigger. Claude reads it before deciding whether to load the full skill.

Progressive Disclosure

Skills work because they avoid loading everything at startup:

Layer	Loaded when	Content
Metadata	Startup	`name`, `description`, and enough detail to decide whether the skill applies
Instructions	Skill is triggered	The operational body of `SKILL.md`
Resources	Needed by the instructions	References, scripts, templates, examples, and assets

Keep the metadata concise and the body procedural. Put long background material in references/ and only point to it when useful.

Custom Commands Are Now Skills

Older Claude Code setups often used .claude/commands/ for custom slash commands. Current Claude Code treats skills as the more capable packaging model. A skill can expose a command-like workflow and also carry references, scripts, and assets.

Prefer skills for new reusable commands. Keep legacy commands only when the repo already depends on them and migration is not worth it yet.

Built-In and Project Skills

Claude Code can load skills from several places:

Built-in skills shipped by Claude Code.
Project skills under .claude/skills/.
User skills under ~/.claude/skills/.
Plugin-provided skills.
Skills discovered from configured marketplaces or team distributions.

Project skills should be committed when they encode team workflow. User skills are better for personal preferences.

Writing Good Skill Descriptions

Bad description:

yaml

description: Helps with databases.

Good description:

yaml

description: Use when adding or changing database migrations, reviewing schema diffs, or investigating migration failures.

A good description names the trigger, not just the topic.

Skills vs Other Extension Points

Need	Use
Persistent project facts	CLAUDE.md or `.claude/rules/`
Reusable procedures and command-like workflows	Skills
Context isolation for noisy work	Subagents
Deterministic enforcement	Hooks
External systems and tools	MCP
Shareable extension bundle	Plugins

Skills are often the first extension to create because they are low-risk and easy to review.

Practical Example

text

Use the database-migration skill to review the migration I just wrote.
Focus on data loss, RLS policy dependencies, and generated TypeScript types.

Claude should load the skill, read any referenced checklist or script only if needed, then apply the workflow to the current repo.