# Commands → Skills Migration: Agent Playbook

> This document is written for AI agents performing the migration. It is not a conceptual guide — it is a step-by-step execution playbook. For rationale and design principles, see `Tips2-migration-guide.md`.

---

## Scope

Migrate all files from `.claude/commands/*.md` to `.claude/skills/*/SKILL.md` format. Preserve all workflow logic. Do not refactor, do not optimize, do not add features.

## Pre-Flight

### Step 1: Inventory

Run these commands and record the output:

```bash
# List all commands
ls .claude/commands/*.md 2>/dev/null

# List all existing skill directories
ls -d .claude/skills/*/

# Find naming conflicts (command name = existing skill directory)
for cmd in .claude/commands/*.md; do
  name=$(basename "$cmd" .md)
  if [ -d ".claude/skills/$name" ]; then
    echo "CONFLICT: $name"
  fi
done
```

Record results in three lists:
- **No conflict**: command name has no matching skill directory
- **Conflict**: command name matches an existing skill directory
- **Oversize**: command file > 300 lines (`wc -l .claude/commands/*.md`)

### Step 2: Verify existing skills in conflict directories

For each CONFLICT entry, read the existing `SKILL.md` and determine its type:

| If existing SKILL.md has... | It is... | Action |
|----------------------------|----------|--------|
| `user-invocable: true` | Already an orchestrator | **SKIP** — already migrated |
| `context: fork` | A forked subagent | **ERROR** — do not overwrite. Ask the user. |
| Neither | A knowledge module | **MERGE** — rename and replace |

---

## Execution: No-Conflict Migration

For each command in the **no conflict** list:

### 1. Create directory

```bash
mkdir -p .claude/skills/{name}/
```

### 2. Create SKILL.md with frontmatter + original content

The SKILL.md must have this exact structure:

```
---
name: {name}
description: "{first line of the original command file}"
user-invocable: true
---

{entire original command file content, unchanged}
```

**Frontmatter rules:**
- `name`: the command filename without `.md` extension, kebab-case
- `description`: copy the first line of the original command file (it is always a one-line description). Wrap in double quotes. Remove trailing period if present.
- `user-invocable: true`: always present for migrated commands

**Content rules:**
- Copy the entire original file content verbatim after the frontmatter
- Do NOT modify workflow steps, file paths, skill references, or any logic
- Do NOT add comments like "migrated from commands"
- Do NOT remove or reorder any sections

### 3. Verify detection

After creating the file, check the system-reminder skill list. The new skill name should appear with its description. If it does not appear:
- Verify the file is at `.claude/skills/{name}/SKILL.md` (exact path)
- Verify the frontmatter has no YAML syntax errors
- Verify `user-invocable: true` is present

---

## Execution: Conflict Migration (MERGE)

For each command in the **conflict** list where the existing SKILL.md is a knowledge module:

### 1. Rename existing knowledge SKILL.md

Choose a descriptive name based on the content:

| Content type | Rename to |
|-------------|-----------|
| Methodology / overview | `methodology.md` |
| Classification rules | `classification-rules.md` |
| Output format | `output-format.md` |
| Mixed / unclear | `reference.md` |

```bash
mv .claude/skills/{name}/SKILL.md .claude/skills/{name}/{descriptive-name}.md
```

### 2. Create new orchestrator SKILL.md

Same process as no-conflict migration (frontmatter + original command content).

### 3. Update skill references

The original command file may already reference the knowledge files by path (e.g., `.claude/skills/slack-digest/channel-classification-rules.md`). These paths are still valid — the supporting files did not move.

However, if the command file references `SKILL.md` of the knowledge module by name, update that reference to the new filename:

```
Before: .claude/skills/slack-digest/SKILL.md
After:  .claude/skills/slack-digest/methodology.md
```

### 4. Verify the knowledge files are still accessible

The renamed knowledge file and all other supporting files in the directory must remain unchanged. Do not modify their content or frontmatter.

---

## Execution: Oversize Files (> 300 lines)

**Default action: do nothing extra.** Migrate as-is. Oversize files are noted for future optimization but are not split during migration.

If the user explicitly requests splitting, follow these rules:

**Candidates for extraction** (move to supporting file):
- Classification rules or decision tables (static knowledge)
- Output format templates (static structure)
- Subagent prompt templates (long embedded text blocks)
- Usage scenarios / examples (reference material)

**Never extract** (must stay in SKILL.md):
- Workflow steps (Step 1 → Step 2 → ...)
- Parameter parsing logic
- Error handling rules
- Skills to Load / Context to Load sections

---

## Post-Migration Cleanup

### 1. Delete old command files

```bash
rm .claude/commands/{name}.md
```

Do this one at a time, after verifying each skill is detected. Do NOT batch delete before verification.

### 2. Remove commands directory (if empty)

```bash
rmdir .claude/commands 2>/dev/null
```

Only remove if completely empty. If other files remain (non-command files), leave the directory.

### 3. Update CLAUDE.md

Find the `## Commands` section in the project's CLAUDE.md. Replace:

```markdown
## Commands

| Command | Purpose |
```

With:

```markdown
## Skills (User-Invocable)

All slash commands are implemented as skills in `.claude/skills/`.

| Skill | Purpose |
```

Keep all table rows unchanged — only the section header and introductory line change.

### 4. Update path references

Search the entire workspace for references to `.claude/commands/`:

```bash
grep -rn "\.claude/commands/" --include="*.md" --include="*.json" . 2>/dev/null
```

For each match:
- If it's a file path reference → update to `.claude/skills/{name}/SKILL.md`
- If it's a conceptual mention (e.g., "the commands directory") → update wording to "skills"
- If it's in a historical document (session handoff, progress log) → leave unchanged (historical accuracy)

### 5. Update memory files

Search the memory directory for old references:

```bash
grep -rn "commands/" ~/.claude/projects/*/memory/ 2>/dev/null
```

Update any file path references to use the new skills paths.

---

## Verification Checklist

Run after all migrations are complete:

```bash
# 1. No remaining command files
ls .claude/commands/*.md 2>/dev/null && echo "FAIL: commands still exist" || echo "PASS"

# 2. All skills detected (count user-invocable)
grep -rl "user-invocable: true" .claude/skills/*/SKILL.md | wc -l

# 3. No broken references to old commands path
grep -rn "\.claude/commands/" --include="*.md" --include="*.json" . 2>/dev/null | grep -v ".git/" | wc -l
# Expected: 0 (or only historical documents)

# 4. Each skill directory has SKILL.md
for dir in .claude/skills/*/; do
  [ -f "${dir}SKILL.md" ] || echo "MISSING: ${dir}SKILL.md"
done
```

---

## Error Recovery

| Error | Recovery |
|-------|----------|
| Created SKILL.md but skill not detected | Check YAML frontmatter syntax. Common issue: missing `---` delimiter or bad indentation |
| Overwrote a forked subagent SKILL.md | `git checkout -- .claude/skills/{name}/SKILL.md` to restore. Then ask user how to handle |
| Command references a skill path that changed | Grep for the old path in the new SKILL.md and update |
| User reports `/command` no longer works | Verify the skill exists at `.claude/skills/{command}/SKILL.md` with `user-invocable: true` |

---

## Do NOT

- Do not refactor workflow logic during migration
- Do not rename skill directories that are not in the conflict list
- Do not modify supporting files (classification rules, output formats, etc.)
- Do not add docstrings, comments, or migration markers to files
- Do not create a backup directory — git history is the backup
- Do not split oversize files unless explicitly asked
- Do not change the order of sections within a migrated SKILL.md