migrate-plugin

name	migrate-plugin
description	Migrate an existing POWER.md-based Kiro Power to the Agent Plugins v1.0.0 specification. Use when converting a power that uses POWER.md frontmatter and steering files to the plugin.json and skills/ format.
license	MIT
metadata	{"author":"Kiro Team","version":"1.0.0"}

Migrate a POWER.md-Based Power to Agent Plugins

Step-by-step guide for converting an existing Kiro Power (POWER.md format) to the Agent Plugins v1.0.0 standard.

Overview

This skill converts the old Kiro Power structure into the portable agent-plugins format:

Old Kiro Power:                  Agent Plugin:
├── POWER.md          →          ├── plugin.json
│   (frontmatter)                ├── skills/
│   (body content)               │   ├── skill-1/
├── mcp.json          →          │   │   ├── SKILL.md
└── steering/         →          │   │   ├── scripts/
    ├── workflow1.md             │   │   └── references/
    └── workflow2.md             │   └── skill-2/
                                 │       └── SKILL.md
                                 └── mcp.json (with $schema + type)

Prerequisites Checklist

• Existing power with POWER.md (and optionally mcp.json, steering/)
• Access to read all existing power files
• Understanding of what the power does and its workflows

Step-by-Step Guide

1. Read the Existing Power

Read all files to understand what needs migrating:

1. Read POWER.md - note the frontmatter fields and body sections
2. Read mcp.json if it exists - note server configurations
3. Read all steering/*.md files - note independent workflows

Identify:

• The power's name, description, keywords, author (from frontmatter)
• Major sections/workflows in the body (each may become a skill)
• Steering files (each independent one may become a skill)
• MCP server configuration details

2. Create the Plugin Directory

mkdir -p {workspace}/powers/{plugin-name}
mkdir -p {workspace}/powers/{plugin-name}/skills

Name validation: 1-64 chars, only a-z, 0-9, -, ., no consecutive -- or .., must start and end alphanumeric.

If the old power name doesn't satisfy these rules, adapt it (e.g., remove uppercase, replace underscores with hyphens).

3. Convert Frontmatter to plugin.json

Map the POWER.md frontmatter fields:

POWER.md Frontmatter	plugin.json	Notes
name	name	Validate against naming rules
displayName	description (incorporate)	No direct equivalent
description	description	Direct mapping
keywords	keywords	Direct mapping (array of strings)
author	author.name	String becomes object with name field

Template transformation:

Given old frontmatter:

---
name: "my-power"
displayName: "My Power"
description: "Does something useful"
keywords: ["tool", "workflow"]
author: "John Doe"
---

Produce:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-power",
  "version": "1.0.0",
  "description": "Does something useful",
  "author": {
    "name": "John Doe"
  },
  "keywords": ["tool", "workflow"],
  "license": "MIT"
}

New fields to add:

• $schema - Always required
• version - Start at "1.0.0" for the migrated version
• license - Choose appropriate license
• repository - Add if the power has a GitHub repo

Fields that don't carry over:

• displayName - No equivalent. Incorporate into description if needed.

4. Convert Body Content to Skills

The most involved step. POWER.md body and steering files decompose into discrete skills.

4.1: Identify Skill Boundaries

Existing Content	Becomes
Single focused POWER.md (< 800 lines)	One skill
POWER.md with multiple independent sections	Multiple skills (one per section)
Each independent steering/*.md file	Its own skill
Related steering files that share context	One skill with references/
Onboarding/setup section	Skill named getting-started or setup
Troubleshooting section	Included in relevant skill, or separate troubleshooting skill

Examples:

A power with POWER.md (overview + setup) and steering/advanced.md:

skills/
├── getting-started/    # from POWER.md setup/overview sections
│   └── SKILL.md
└── advanced/           # from steering/advanced.md
    └── SKILL.md

A power with POWER.md (everything in one file, < 800 lines):

skills/
└── main/              # entire POWER.md body
    └── SKILL.md

A power with multiple steering files:

skills/
├── web-scraping/      # from steering/web-scraping.md
│   └── SKILL.md
├── e2e-testing/       # from steering/e2e-testing.md
│   └── SKILL.md
└── performance/       # from steering/performance.md
    └── SKILL.md

4.2: Write SKILL.md for Each Skill

For each identified skill:

mkdir -p {workspace}/powers/{plugin-name}/skills/{skill-name}

Transform the content:

1. Add frontmatter - Every SKILL.md needs:

   ---
   name: "{skill-name}"
   description: "{What it does}. Use when {trigger conditions}."
   license: "MIT"
   metadata:
     author: "{author from old power}"
     version: "1.0.0"
   ---
   

2. Restructure the body:

   • Add ## Overview section (from old overview/intro)
   • Add ## Prerequisites Checklist with checkboxes
   • Convert workflows to ## Step-by-Step Guide with numbered steps
   • Keep ## Troubleshooting section
   • Keep ## Best Practices section

3. Extract heavy content if skill exceeds 800 lines:

   • Reference tables, API docs → references/
   • Code examples, templates → assets/
   • Helper scripts → scripts/
   • Link from SKILL.md: See [API reference](references/api.md)

4.3: Handle Cross-Cutting Content

Content that applies to all skills (general overview, common config):

1. Deduplicate into each skill - If short (< 10 lines), include in each overview
2. Create a getting-started skill - For shared setup/onboarding
3. Use references/ - Put shared docs in one skill's references and link from others

5. Convert mcp.json

If the old power has mcp.json, it needs two additions:

5.1: Add Schema Reference

Old:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@example/server"],
      "env": {
        "API_KEY": "API_KEY"
      }
    }
  }
}

New:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/server"],
      "env": {
        "API_KEY": "API_KEY"
      }
    }
  }
}

5.2: Determine Transport Type

Old Configuration	Type to Add
Has command (and optionally args, env, cwd)	"stdio"
Has url pointing to HTTP endpoint	"streamable-http"
Has url with SSE endpoint (legacy)	"sse"

5.3: Remove Non-Spec Fields

Remove from mcp.json (these are Kiro-specific):

• disabled
• autoApprove
• disabledTools

If these need to be preserved, put them in plugin.json extensions:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "extensions": {
    "dev.kiro": {
      "disabledTools": ["tool1", "tool2"],
      "autoApprove": ["tool3"]
    }
  }
}

5.4: Fix Field Compatibility

• command must be a single token - If it's a shell string, extract executable and put args in args
• Check env keys - Remove any PLUGIN_ROOT or PLUGIN_DATA entries
• Check cwd - Must start with ./, ${PLUGIN_ROOT}, or ${PLUGIN_DATA} if present

6. Remove Old Files

Once migration is complete and validated:

• Delete POWER.md (replaced by plugin.json + skills/*/SKILL.md)
• Delete steering/ directory (content moved to skills)
• Keep mcp.json (updated in place with $schema and type)

Or, if creating in a new directory, use the new directory as the power source.

7. Validate the Migration

Structure Validation

{plugin-name}/
├── plugin.json                    # Has $schema, name
├── skills/
│   └── {skill}/
│       └── SKILL.md              # Has name, description in frontmatter
└── mcp.json                       # Has $schema, mcpServers with type

Content Validation Checklist

• plugin.json has required $schema and name fields
• plugin.json name satisfies naming constraints
• All skills have SKILL.md with name and description in frontmatter
• Each skill name matches its directory name
• Each skill description starts with a verb and includes when to use
• SKILL.md files are 400-800 lines (excess moved to references/)
• mcp.json (if present) has $schema field
• Each MCP server entry has a type field
• No Kiro-specific fields remain in mcp.json
• No files reference paths outside the plugin root
• No secrets in configuration files
• All code examples are complete and copy-paste ready

Functional Validation

1. Install the new plugin locally via Kiro Powers UI
2. Test that skills trigger for relevant user queries
3. Test MCP tools work (if applicable)
4. Verify all workflows still function end-to-end
5. Compare behavior with the old power to ensure nothing was lost

Migration Examples

Example 1: Simple Power (Single POWER.md, No Steering)

Before:

weather/
├── POWER.md    (frontmatter + all docs in body)
└── mcp.json

After:

weather/
├── plugin.json
├── skills/
│   └── weather/
│       └── SKILL.md    (body content from old POWER.md)
└── mcp.json            (+ $schema + type on each server)

Example 2: Power with Steering Files

Before:

playwright/
├── POWER.md             (overview + common patterns)
├── mcp.json
└── steering/
    ├── web-scraping.md
    ├── e2e-testing.md
    └── performance.md

After:

playwright/
├── plugin.json
├── skills/
│   ├── web-scraping/
│   │   └── SKILL.md    (from steering/web-scraping.md)
│   ├── e2e-testing/
│   │   └── SKILL.md    (from steering/e2e-testing.md)
│   └── performance/
│       └── SKILL.md    (from steering/performance.md)
└── mcp.json             (+ $schema + type)

Example 3: Knowledge Base Power (No MCP)

Before:

testing-strategies/
├── POWER.md             (overview/index)
└── steering/
    ├── unit-testing.md
    ├── integration-testing.md
    └── e2e-testing.md

After:

testing-strategies/
├── plugin.json
└── skills/
    ├── unit-testing/
    │   └── SKILL.md
    ├── integration-testing/
    │   └── SKILL.md
    └── e2e-testing/
        └── SKILL.md

Troubleshooting

Issue: POWER.md body is too large for one skill

Solution: Break into multiple skills by workflow area. Each independent section becomes its own skill. Shared setup becomes a getting-started skill.

Issue: Steering file references other steering files

Solution: Skills can reference each other using relative paths from the plugin root: See [related skill](../other-skill/SKILL.md). Or consolidate related content into one skill with references/.

Issue: mcp.json has fields not in the spec

Solution: Move Kiro-specific fields (disabled, autoApprove, disabledTools) to extensions.dev.kiro in plugin.json. Remove them from mcp.json.

Issue: Power name has uppercase or underscores

Solution: Convert to lowercase with hyphens. MyPower_Name becomes my-power-name.

Issue: Single POWER.md under 800 lines

Solution: Simplest case. Create one skill with the body as SKILL.md. Frontmatter moves to plugin.json.

Agent Guidelines

Process

1. Always read ALL existing files before starting migration
2. Present a migration plan to the user before generating files
3. Show the proposed skill breakdown and get confirmation
4. Generate all files, then validate
5. Offer to test the migrated plugin

Content Transformation

• Don't just copy-paste. Restructure to fit the SKILL.md format.
• Add proper frontmatter with name and description to every SKILL.md
• Ensure description includes trigger conditions ("Use when...")
• Convert prose overviews to structured sections (Overview, Prerequisites, Steps)
• Extract code into fenced blocks with language tags

Preserve Intent

• Don't lose workflows or troubleshooting content
• If the old power had tool-disabling logic, preserve it in extensions
• Keep all MCP tool documentation accurate
• Maintain keyword specificity