After:

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

Migration Steps:

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

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:

First line after # heading
First paragraph of content
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

Filename	Derived Name
`my-skill.md`	`my-skill`
`MySkill.md`	`myskill`
`my_skill.md`	`my-skill`
`My Skill.md`	`my-skill`

Rules:

Lowercase everything
Replace underscores/spaces with hyphens
Remove non-alphanumeric except hyphens
Ensure starts with letter

Detecting Tool Usage

Scan content for tool references:

Pattern	Tool
"read file", "Read tool"	Read
"search", "grep", "find text"	Grep
"find files", "glob"	Glob
"run command", "bash", "execute"	Bash
"write", "create file"	Write
"edit", "modify"	Edit

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

migration-guide

Plugin Migration Guide

Common Migration Scenarios

1. Flat Skills to Directory Format