Commands → Skills Migration Guide

Claude Code v2.1.3 merged Custom Commands into the Skills system. If you’re still using .claude/commands/, this guide explains the differences and provides a Playbook you can hand directly to your Agent.

For background on the merge, community reactions, and impact analysis, see News: Are Slash Commands Dead?. This article focuses on how to migrate.

---

Core Differences: Commands vs Skills

	Commands	Skills
File structure	Single file (.claude/commands/deploy.md)	Directory (.claude/skills/deploy/SKILL.md)
Supporting files	Not supported	Supported (rules, templates, prompts)
Frontmatter	Not supported	Supported (description, user-invocable, context: fork, model)
Knowledge separation	Everything in one file	SKILL.md + supporting files, JIT loaded
Subagent isolation	Not possible	context: fork natively supported

In one sentence: Commands = “one instruction, one file.” Skills = “one capability, one directory.”

---

Three Types of Skills

Before migrating, understand that every Skill belongs to exactly one of three types:

1. Orchestrator

The entry point triggered by /daily. Defines “what to do, in what order.” Has user-invocable: true.

Your migrated Commands will all become this type.

2. Knowledge

Methodology and rules that tell the Agent “how to classify” or “how to judge.” No user-invocable — loaded on-demand by Orchestrators.

3. Forked Subagent

Runs tasks in isolated context, returns concise results. Uses context: fork + allowed-tools.

User types /daily
       ↓
  Orchestrator (daily/SKILL.md)
    ├── Load Knowledge (rules files)
    ├── Delegate to Subagent → returns summary
    └── Produce output

---

Basic Migration Steps

No Conflict (most cases)

When your command name doesn’t collide with an existing skill directory:

Before: .claude/commands/deploy.md
After:  .claude/skills/deploy/SKILL.md

1. Create directory .claude/skills/deploy/
2. Add frontmatter (name, description, user-invocable: true)
3. Paste original command content after frontmatter — unchanged
4. Delete the original command file

With Conflict (command name = existing skill directory)

When the target directory already has a SKILL.md (usually a Knowledge module):

1. Rename existing SKILL.md to a descriptive name (e.g., methodology.md)
2. Create new SKILL.md with command content (Orchestrator)
3. Reference the renamed knowledge file from the new SKILL.md

---

Migration Tips

Line Count Guidelines

Lines	Status
< 200	Ideal
200–300	Acceptable
300–500	Long — consider splitting
> 500	Must split

Beyond 300 lines, LLM instruction-following degrades noticeably. But don’t split for the sake of splitting — a coherent 350-line file is better than 200 lines + two fragments.

Good candidates for extraction

• Classification rules, decision tables
• Output format templates
• Subagent prompt templates
• Usage scenarios / examples

Must stay in SKILL.md

• Workflow steps (Step 1 → Step 2 → …)
• Error handling logic
• Skills to Load sections

Post-migration cleanup

After migrating, remember to:

1. Delete the .claude/commands/ directory
2. Update the Commands section in CLAUDE.md
3. Search for all .claude/commands/ path references — update to .claude/skills/
4. Check memory files for stale path references

---

Download the Agent Playbook

The above is a human-readable guide. If you want your Agent to execute the migration automatically, download this Playbook:

📥 Download Agent Playbook (.md)

How to use: Download and place in your project directory, then tell Claude Code:

Read commands-to-skills-migration-playbook.md and follow the steps to migrate my Commands to Skills

The Agent will follow the Playbook automatically: Inventory → Create Skills → Handle conflicts → Clean up → Verify.

---

Related resources:

• News: Are Slash Commands Dead? — Background and community reactions
• Extend Claude with skills — Official Docs
• Issue #37447 — Commands deprecation timeline