Create Plugin

Create a New Agent Plugin

Interactive workflow for creating a Kiro Power that conforms to the Agent Plugins specification v1.0.0.

Overview

This skill guides you through creating a portable plugin with:

• A plugin.json manifest
• One or more skills (each with SKILL.md)
• Optional mcp.json for MCP server integration
• Optional helper scripts, references, and assets

Workflow Overview

1. Understand the user's use case
2. Determine plugin components (skills, MCP, or both)
3. Create plugin directory and plugin.json
4. Create skills (SKILL.md + supporting files)
5. Create mcp.json (if MCP server involved)
6. Test and install locally

Step-by-Step Guide

1. Understand the Use Case

Have a natural conversation to understand:

• What problem does this plugin solve?
• Does it involve an MCP server? (needs mcp.json)
• What distinct tasks/workflows does it enable? (each becomes a skill)
• Is it pure documentation/guidance? (skills only, no mcp.json)
• Who is the audience?

Through this conversation, determine:

• The plugin name (lowercase, hyphens, 1-64 chars, no --)
• Whether it needs mcp.json (MCP server integration)
• How many skills it needs (one per distinct workflow/concern)
• Basic metadata (description, keywords, author)

2. Create Plugin Directory

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

Tell the user the location: {workspace}/powers/{plugin-name}/

3. Generate plugin.json

Create the manifest. Always required.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "{plugin-name}",
  "version": "1.0.0",
  "description": "{description}",
  "author": {
    "name": "{author-name}"
  },
  "keywords": ["{keyword1}", "{keyword2}", "{keyword3}"],
  "license": "MIT"
}

Validation checklist:

• $schema is exactly https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
• name matches directory name
• name is 1-64 chars, lowercase a-z0-9.-, no -- or .., starts/ends alphanumeric
• No fields beyond: $schema, name, version, description, author, homepage, repository, license, keywords

4. Create Skills

For each distinct workflow or concern, create a skill directory with SKILL.md.

4.1: Determine Skill Boundaries

Each skill should be a self-contained unit covering one task area. Split when:

• Workflows are independent (a user would use one without the other)
• Content exceeds 800 lines (break into focused skills)
• Different prerequisites or contexts

Keep together when:

• Steps form a single workflow
• Content is under 800 lines
• Users always need all the information together

4.2: Create Skill Directory

For each skill:

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

4.3: Write SKILL.md

Each skill needs a SKILL.md with frontmatter and markdown body:

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

# {Skill Title}

## Overview
{2-3 sentences: what this skill does, why it's useful, key capabilities.}

## Prerequisites Checklist
- [ ] {Requirement 1}
- [ ] {Requirement 2}

## Step-by-Step Guide

### 1. {First Step}
{Clear instructions with code examples}

### 2. {Second Step}
{Instructions...}

## Common Workflows

### Workflow: {Name}
**Goal:** {What this accomplishes}

## Troubleshooting

### Error: "{common error message}"
**Cause:** {why it happens}
**Solution:**
1. {fix step}
2. {verify step}

## Best Practices
- {Practice 1}
- {Practice 2}
- {Practice 3}

SKILL.md validation:

• Frontmatter name matches directory name exactly
• description starts with a verb, max 1024 chars
• description includes "Use when..." trigger phrase
• Body is 400-800 lines (move excess to references/)
• Code examples are complete and copy-paste ready
• All relative paths reference files within the skill directory

4.4: Add Supporting Files (Optional)

scripts/ - Helper scripts the agent or user can execute:

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

Focus on core logic, < 500 lines. The agent may regenerate with appropriate parameters.

references/ - Additional documentation too large for SKILL.md:

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

Use for: API references, detailed examples, checklists, extended troubleshooting.

assets/ - Templates, config files, static resources:

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

Use for: boilerplate templates, example configs, starter files.

5. Create mcp.json (If Needed)

Only create mcp.json if the plugin integrates with an MCP server.

5.1: Gather MCP Server Information

Check if the user already has the MCP server configured in Kiro:

• Workspace: .kiro/settings/mcp.json
• User: ~/.kiro/settings/mcp.json

If configured, read the existing config and adapt it. If not, ask the user for:

• How the server is started (command, npm package, binary)
• Required environment variables
• Whether it's local (stdio) or remote (HTTP)

5.2: Generate mcp.json

For local (stdio) servers:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "{server-name}": {
      "type": "stdio",
      "command": "{command}",
      "args": ["{arg1}", "{arg2}"],
      "env": {
        "{ENV_VAR}": "{value-or-placeholder}"
      }
    }
  }
}

For remote servers:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "{server-name}": {
      "type": "streamable-http",
      "url": "https://example.com/mcp",
      "headers": {
        "X-Tenant": "public-value"
      }
    }
  }
}

mcp.json validation:

• $schema is exactly https://agent-plugins.org/schemas/1.0.0/mcp.schema.json
• Each server has a type field (stdio, streamable-http, or sse)
• stdio: command is a single token (not a shell string)
• stdio: command is either a bare name or starts with ./
• env does not contain PLUGIN_ROOT or PLUGIN_DATA keys
• If cwd present: starts with ./, ${PLUGIN_ROOT}, or ${PLUGIN_DATA}
• Remote URLs are HTTPS (HTTP only for localhost)
• No secrets in env or headers
• No fields beyond those defined per transport type

5.3: Sanitize for Sharing

If the mcp.json contains user-specific values, replace with placeholders and document them in the relevant skill's SKILL.md under a "Configuration" section.

6. Final Structure Validation

Verify the complete plugin:

{plugin-name}/
├── plugin.json                    # Required
├── skills/                        # At least one skill recommended
│   ├── {skill-1}/
│   │   ├── SKILL.md              # Required per skill
│   │   ├── scripts/              # Optional
│   │   ├── references/           # Optional
│   │   └── assets/               # Optional
│   └── {skill-2}/
│       └── SKILL.md
└── mcp.json                       # Only if MCP server involved

Final checklist:

• plugin.json exists at root with valid $schema and name
• All skills have SKILL.md with valid frontmatter
• Skill name in frontmatter matches directory name
• mcp.json (if present) has valid $schema and mcpServers
• No files reference paths outside the plugin root
• No secrets in any configuration files

7. Test and Install

Install Locally

1. Open Kiro Powers UI (call action="configure")
2. Click "Add Custom Power" at the top
3. Select "Local Directory"
4. Provide the absolute path: {workspace}/powers/{plugin-name}
5. Click "Add"

Test

1. Use the "Try Power" button on the power's detail page
2. Also test in a fresh agent chat session
3. Make natural language requests that should trigger the power's skills
4. Verify MCP tools work if applicable

Iterate

If issues found:

1. Edit files in {workspace}/powers/{plugin-name}/
2. In Powers UI, navigate to the installed power
3. Click "Check for Updates" then "Update Power"
4. Re-test

Sharing

GitHub Repository

Push to a public GitHub repository. Users add the repo URL in Kiro Powers UI.

Before sharing:

• Sanitize mcp.json (replace secrets with placeholders)
• Document all placeholders in relevant SKILL.md files
• Include a LICENSE file

Kiro Recommended Powers

Submit at: https://kiro.dev/powers/submit/

Requirements:

• Public GitHub repository
• Complete documentation and testing
• Sanitized configuration
• Clear use cases and examples

Agent Guidelines

Do

• Ask questions one at a time, don't overwhelm
• Generate complete files, never leave {TODO} placeholders
• Use exact MCP tool names from documentation
• Include copy-paste-ready examples
• Validate all files against the spec before finishing

Don't

• Don't add fields not in the spec schemas
• Don't use shell command strings in command (single token only)
• Don't embed secrets in config files
• Don't create overly broad keywords that cause false activations
• Don't skip the $schema field on plugin.json or mcp.json
• Don't put PLUGIN_ROOT or PLUGIN_DATA as keys in env