Migration Guide

Plugin Migration Guide

This skill provides procedures for migrating plugins to the correct Claude Code format.

Common Migration Scenarios

1. Flat Skills to Directory Format

Before:

skills/
├── my-skill.md
└── another-skill.md

After:

skills/
├── my-skill/
│   └── SKILL.md
└── another-skill/
    └── SKILL.md

Migration Steps:

1. For each skills/*.md file:

   # Create directory
   mkdir -p skills/skill-name
   
   # Move and rename
   mv skills/skill-name.md skills/skill-name/SKILL.md
   

2. Add frontmatter if missing:

   ---
   name: skill-name
   description: [extracted from content or prompted]
   ---
   

2. Adding Missing Frontmatter

Skills without frontmatter:

Check if file starts with ---. If not, add:

---
name: [derive from filename, lowercase, hyphens]
description: [extract first paragraph or prompt user]
allowed-tools: [analyze content for tool usage]
---

[existing content]

Agents without frontmatter:

---
name: [derive from filename]
description: [extract purpose from content]
tools: [analyze for tool references]
model: sonnet
---

[existing content]

3. Moving Directories to Plugin Root

Issue: Directories inside .claude-plugin/

Before:

.claude-plugin/
├── plugin.json
├── commands/
├── agents/
└── skills/

After:

.claude-plugin/
└── plugin.json
commands/
agents/
skills/

Migration:

# Move directories to root
mv .claude-plugin/commands ./commands
mv .claude-plugin/agents ./agents
mv .claude-plugin/skills ./skills

4. Removing Empty Directories

Check for and remove empty directories:

# Find empty directories
find . -type d -empty

# Remove specific empty dirs
rmdir agents/  # if empty
rmdir commands/  # if empty

Frontmatter Extraction

Extracting Description from Content

Look for description in order:

1. First line after # heading
2. First paragraph of content
3. File's first sentence

Example:

# My Skill

This skill helps with X, Y, and Z.

## Instructions
...

Extract: "This skill helps with X, Y, and Z."

Deriving Name from Filename

Rules:

1. Lowercase everything
2. Replace underscores/spaces with hyphens
3. Remove non-alphanumeric except hyphens
4. Ensure starts with letter

Detecting Tool Usage

Scan content for tool references:

Migration Checklist

Pre-Migration

• Backup existing plugin
• List all files to migrate
• Identify content to extract

During Migration

• Convert flat skills to directories
• Add frontmatter to all skills
• Add frontmatter to all agents
• Move directories to plugin root
• Remove empty directories
• Update plugin.json paths

Post-Migration

• Run /pb:validate on migrated plugin
• Test all commands appear in /help
• Verify skills are discovered
• Check agents can be invoked
• Remove backup after verification

Handling Edge Cases

Skills with Reference Files

If skill has associated files:

Before:

skills/
├── api-reference.md
└── api-reference-data.json

After:

skills/
└── api-reference/
    ├── SKILL.md
    └── data.json

Nested Command Directories

Preserve namespace structure:

Before:

commands/
└── git/
    ├── commit.md
    └── push.md

After: (no change needed - already correct)

commands/
└── git/
    ├── commit.md  → /git:commit
    └── push.md    → /git:push

Multiple Content Files per Skill

Move all related files to skill directory:

skills/
└── complex-skill/
    ├── SKILL.md
    ├── reference.md
    ├── examples.md
    └── templates/
        └── template.json