Build a plugin

A Reforma plugin equips the builder agent in the editor with specialized capabilities, domain knowledge, and external tools. It is not runtime code or SDKs bundled into your published end-user application.

Reforma follows the Agent Plugins standard. Portable plugin metadata stays at the top level of plugin.json; Reforma-specific presentation and execution settings live under extensions.reforma.

A plugin can be tiny. A single rule or a single skill is a completely valid plugin. Add only what you need.

Plugin structure

Plugins are authored as a directory with a root plugin.json and convention folders for each capability:

my-plugin/
├── plugin.json
├── assets/
│   └── logo.svg
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── rules/
│   └── my-rule.md
├── mcp.json
├── tools/
│   └── MyTool.ts
├── hooks/
│   └── hooks.json
└── agents/
    └── my-agent.md

Everything except plugin.json is optional.

Capability	Path	Use it for
MCP	`mcp.json`	Connect the agent to external services and live APIs. MCP servers
Skills	`skills/<name>/SKILL.md`	Playbooks and procedures loaded when relevant. Can also be slash commands. Skills
Rules	`rules/*.md`	Always-on instructions applied on every turn. Rules
Tools	`tools/*.ts`	Deterministic TypeScript code executed in the Reforma sandbox. Tools
Hooks	`hooks/hooks.json`	Deterministic scripts triggered by agent lifecycle events. Hooks
Agents	`agents/*.md`	Specialized subagent personas shipped by the plugin.

Create the manifest

Start with a minimal plugin.json:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "description": "What this plugin gives the person installing it."
}

name: Unique kebab-case identifier matching your plugin directory.
description: The pitch in the marketplace. Describe the value to the user, not internal technical plumbing.

To customize how the card appears in the Reforma catalog, add extensions.reforma:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "description": "What this plugin gives the person installing it.",
  "extensions": {
    "reforma": {
      "logo": "assets/logo.svg",
      "interface": {
        "displayName": "My Plugin",
        "brandColor": "#D97348"
      }
    }
  }
}

See Plugin manifest for the full schema reference.

Add it to the catalog

The Reforma catalog index is maintained in reforma-ai/plugins.

Clone the repository and install dependencies:

git clone https://github.com/reforma-ai/plugins.git
cd plugins
bun install

1. Place the plugin

Direct contribution: place your plugin directory under its catalog category:
```
marketplace/<category>/<name>/
```
External repository: if your plugin is hosted in a public GitHub repository, keep it there. You only need to register its pinned URL in the next step.

2. Register in `marketplace.json`

Add your plugin to the corresponding category in marketplace.json:

{
  "id": "demo",
  "name": "Demo",
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./marketplace/demo/my-plugin"
    }
  ]
}

For external plugins, set source to a pinned GitHub tree/... URL (e.g. https://github.com/org/repo/tree/v1.0.0/plugin).

Do not set category inside plugin.json. The catalog assigns categories based on the parent entry in marketplace.json.

Validate and submit

Test that the catalog packer resolves and normalizes your plugin:

bun run pack

The packer validates all sources, normalizes convention paths, bundles tools, and outputs build artifacts to dist/catalog/.

Once bun run pack succeeds with no errors, open a Pull Request against reforma-ai/plugins.

Ecosystem compatibility

Reforma automatically ingests plugins built for Cursor, Claude, or Codex. During packing, vendor-specific files (such as .cursor-plugin, rules/*.mdc, or .mcp.json) are automatically hoisted and mapped to the standard Agent Plugins format.