Slash Commands Are Now Skills: Migrating Commands to Skills

Since Claude Code v2.1.3, a file at .claude/commands/deploy.md and a folder at .claude/skills/deploy/SKILL.md both create the exact same /deploy slash command. You do not have to migrate your commands to skills, because plain commands still work and have no announced retirement date. You should migrate anyway when you want one of the features only skills offer: Claude calling the workflow on its own, isolated subagent runs, shell output injected before the prompt, and the same file working in 30+ other AI tools.

The short version of the merge

Claude Code used to treat custom slash commands and skills as two separate systems. As of v2.1.3, they merged. Both .claude/commands/ markdown files and .claude/skills/ folders register slash commands the same way.

Two plain-language points:

• If a command and a skill share a name, the skill wins. So .claude/skills/deploy/SKILL.md overrides .claude/commands/deploy.md.
• There is no deprecation date for plain commands. The GitHub tracking issue asking to remove them was closed as "not planned" in March 2026 (reported). So your existing .claude/commands/ files keep running.

A "slash command" here just means a shortcut you type, like /deploy, that runs a saved instruction. A "skill" is the newer format: a folder with a SKILL.md file inside, plus any helper files it needs.

Why this matters to you

The real reason to move is portability. A SKILL.md file follows the Agent Skills open standard, a shared format for describing a reusable workflow. As of June 2026 that standard is adopted by 30+ tools including Cursor, GitHub Copilot, VS Code, Gemini CLI, OpenAI Codex, and JetBrains Junie (reported). So a skill you write once for Claude Code can run unchanged in those other tools. A plain command in .claude/commands/ is Claude-only.

In plain terms: migrating is opting into an open format, not doing Claude housekeeping.

Commands vs Skills at a glance

How to migrate a command to a skill

The full required change is small. Three steps:

1. Make a folder: .claude/skills/<command-name>/. For a command named deploy, that is .claude/skills/deploy/.
2. Move your markdown into a file called SKILL.md inside that folder. The body of instructions stays the same.
3. Add a description: line in the frontmatter at the top of SKILL.md. Frontmatter is the small YAML block between two --- lines.

That is it. Optionally add a when_to_use: line to tell Claude when the skill should fire on its own. Here is a minimal example:

---
description: Deploy the app to production via the deploy script
when_to_use: When the user asks to ship, release, or deploy to prod
---

Run the deploy checklist, then execute scripts/deploy.sh and report the URL.

The instruction body below the frontmatter is identical to what you had in your old command file.

The 13 frontmatter fields, and the 3 that matter

A SKILL.md supports 13 optional frontmatter fields. Most users only need three:

• description: a short label, shown in the skill list and read by Claude to decide whether to call the skill on its own. This is what powers auto-invocation, meaning Claude runs the skill without you typing the slash command.
• when_to_use: a longer prose hint describing the trigger conditions. The description and when_to_use text are truncated together at 1,536 characters in the skill listing, which keeps the startup cost small. Keep both tight.
• context: fork: runs the skill in an isolated subagent, a separate Claude instance that does the work and reports back without cluttering your main chat. Plain commands have no equivalent. This is the closest thing to Claude Code subagents you get from a single file.

The other fields cover things like paths: for scoping and model selection. Start with the three above.

The most useful feature: shell output injection

Both skills and commands support dynamic context injection with the !`command` syntax. Claude runs that shell command first and pastes the output into the prompt before reading the rest of the skill.

Example inside a SKILL.md body:

Here is the current diff:

!`git diff HEAD`

Review it for bugs and suggest a commit message.

When the skill runs, Claude executes git diff HEAD, drops the real diff into the prompt, then follows your instructions. Your skill reacts to live state instead of stale text. This single feature is the biggest practical reason builders write skills at all.

Token cost: keep the body tight

Skills are cheap at startup. Only the name and description of each skill load when Claude Code boots. The full skill body loads once the skill is triggered, and then it stays in context for the rest of the session.

The catch: a long skill body is a repeating cost on every turn after it fires, because it sits in the conversation. So write short, direct bodies. A skill that is three screens of prose will quietly eat your context window all session. The same discipline you use for CLAUDE.md applies here.

Monorepo scoping and live edits

Two more things worth knowing for bigger projects:

• Nested scoping: you can put a .claude/skills/ folder deep inside a monorepo so a skill only applies to that package. The paths: frontmatter field takes a glob (a wildcard pattern like apps/web/**) to narrow where a skill is relevant.
• Live change detection: editing an existing skill applies in your current session, no restart needed. But adding a brand-new top-level skills directory needs a Claude Code restart before it is picked up.

The $29 Code Kit from Build This Now ships its agents, skills, and hooks already wired as skills, so you get working SKILL.md files to copy from instead of guessing at the format, alongside patterns like row-level security and MCP servers.

FAQ

Do I have to migrate from .claude/commands to skills in Claude Code?

No. Both paths still work and produce identical slash commands. There is no announced deprecation date, and the tracking issue was closed as "not planned" in March 2026 (reported). Migrate only when you want auto-invocation, cross-tool portability, or features like context: fork that plain commands do not support.

What is the difference between Claude Code commands and skills?

Functionally they create the same slash command. Skills add 13 optional frontmatter fields, including auto-invocation via description, isolated subagent runs via context: fork, dynamic shell-output injection, and portability across the 30+ AI tools that adopt the Agent Skills open standard.

How do I convert a .claude/commands file to a skill?

Create a directory at .claude/skills/<command-name>/ and move your markdown into a SKILL.md file inside it. Add a description: frontmatter field at the top. That is the minimum required change.

What is the difference between Claude Code skill description and when_to_use?

description is the short label shown in the skill list and used by Claude to decide whether to auto-invoke the skill. when_to_use is a longer prose block giving richer guidance on trigger conditions. Together they are truncated at 1,536 characters in the skill listing to control context cost.