Claude Code Skills and Slash Commands

Skills and commands are now one thing

For years Claude Code had two separate features: slash commands (a Markdown file you triggered with /name) and Skills (a richer, self-contained capability). In 2026 they were unified. Custom commands have been merged into Skills, so both create a slash command and behave the same way. Your existing .claude/commands/ files keep working, and Skills simply add optional features on top: a directory for supporting files, frontmatter to control who invokes them, and the ability for Claude to load them automatically when relevant. Claude Code Skills follow the open Agent Skills standard, so the same skill can work across tools.

• A file at .claude/commands/deploy.md creates /deploy.
• A Skill at .claude/skills/deploy/SKILL.md also creates /deploy.
• Skills add: supporting files, invocation control, and automatic loading by description.
• Existing .claude/commands/ files still work; Skills are the recommended path forward.

Creating a slash command

The simplest reusable workflow is a Markdown file whose name becomes the command. Drop a file in .claude/commands/ (project) or ~/.claude/commands/ (personal) and Claude Code exposes it as a slash command. Use the $ARGUMENTS placeholder to capture whatever you type after the command, or positional $1, $2 for individual arguments. A description in the YAML frontmatter shows up as help text. This is perfect for a single, well-defined action you trigger often.

<!-- .claude/commands/fix-issue.md -->
---
description: Investigate and fix a GitHub issue by number.
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS. First read the issue with the gh CLI, then
find the relevant code, propose a fix in plan mode, and only implement
after I approve. Run the test suite before you say it is done.

Writing a SKILL.md

A Skill is a directory with a SKILL.md file at its root: YAML frontmatter plus Markdown instructions, and optionally bundled scripts, templates or reference files. The directory name becomes the command you type, and the description is what Claude reads to decide when to load the skill automatically, so a sharp description is half the work. Only the description is recommended; everything else is optional. Skills shine when a workflow is multi-step, has its own assets, or you want Claude to invoke it on its own when the moment fits.

<!-- .claude/skills/summarize-changes/SKILL.md -->
---
description: Summarise uncommitted changes and flag risks. Use when the user asks what changed or wants a commit message.
allowed-tools: Read, Grep
---

## Current changes

!`git diff HEAD`

## Instructions

Summarise the changes above in two or three bullet points, then list any
risks such as missing error handling, hardcoded values, or tests that need
updating. If the diff is empty, say there are no uncommitted changes.

The line with !`git diff HEAD` is dynamic context injection: Claude Code runs the command and replaces the line with its output before the model sees the skill, so the instructions arrive with your real diff already inlined. Keep the body concise, because once a skill loads its content stays in context across turns.

Where they live and who invokes them

Project Skills live in .claude/skills/<name>/SKILL.md and apply to that repo; personal Skills live in ~/.claude/skills/<name>/SKILL.md and follow you everywhere. Claude can invoke a Skill automatically when your request matches its description, or you can trigger it directly with /name. If a workflow should only ever run when you ask for it (a deploy, say), set disable-model-invocation: true so Claude never triggers it on its own. To hide a knowledge-only skill from the slash menu, set user-invocable: false.

• Project: .claude/skills/<name>/SKILL.md - shared with the repo.
• Personal: ~/.claude/skills/<name>/SKILL.md - all your projects.
• Auto-invoked by description, or triggered directly with /name.
• disable-model-invocation: true makes a skill manual-only; user-invocable: false hides it from the / menu.

When to use which

The signal to package anything is repetition: the second time you brief the agent on the same sequence, capture it. Then choose the form by how rich it is. A single clear action with no assets is a plain command file. A multi-step process with its own templates, scripts or reference docs, or one you want Claude to load automatically, is a Skill. You can start with a command and grow it into a Skill later. Keep your library small and focused: two or three you actually reach for beat twenty you forget exist.

Step by step

1. 01

   Pick a workflow you repeat

   Choose the multi-step instruction you find yourself retyping, such as a deploy, a commit-and-PR flow, or a scaffold-and-test routine.

2. 02

   Start with a command file

   Create .claude/commands/<name>.md with your prompt and a description in the frontmatter. Use $ARGUMENTS to accept input. Invoke it as /<name>.

3. 03

   Promote to a SKILL.md if it grows

   When the workflow needs bundled files or you want Claude to load it automatically, create .claude/skills/<name>/SKILL.md with a sharp description. The directory name becomes the command.

4. 04

   Add dynamic context if useful

   Inline live data with a !`command` line (for example !`git diff HEAD`) so the skill arrives with real context already filled in.

5. 05

   Set invocation control

   For workflows that should only run on request, add disable-model-invocation: true so Claude never triggers them on its own. Keep the body concise to limit context cost.

Frequently asked questions

Keep learning