Plugin format

Reforma plugins use the Agent Plugins format.

Every plugin has a root plugin.json. Portable Agent Plugins fields stay at the top level; Reforma-specific configuration lives under extensions.reforma.

Capabilities like skills, rules, MCP servers, hooks, and tools are discovered from convention paths, so plugins do not need to declare those paths in the manifest.

plugin.json

A minimal plugin starts with:

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

Use top-level fields for portable metadata:

Field	Purpose
`name`	Unique kebab-case plugin identifier
`description`	Marketplace pitch explaining the user value
`version`	Semantic version string
`author`	Author name or object
`homepage`	Project homepage URL
`repository`	Source code repository
`license`	License identifier (e.g. `MIT`, `Apache-2.0`)
`keywords`	Tags for catalog search and discovery

$schema is recommended in source manifests for editor autocompletion and validation. The catalog packer automatically adds it if omitted.

See the Agent Plugins manifest specification for the full portable schema.

Reforma extensions

Store Reforma-specific metadata under 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"
      },
      "agent": {
        "mentions": ["example.com"]
      }
    }
  }
}

Available fields:

Field	Purpose
`logo`	Relative path to the plugin logo (`assets/logo.svg`). Stamped with a CDN URL during catalog release.
`logoSmall`	Optional 12–14px glyph for compact chips and chat chrome. Falls back to `logo`.
`interface.displayName`	User-facing display name in the catalog and editor.
`interface.brandColor`	Hex background plate color behind the logo.
`interface.brandColorDark`	Optional background plate color for dark mode.
`variables`	JSON Schema defining configuration options and API keys. Values are securely stored in the project vault. See MCP servers.
`agent.mentions`	Terms or product domains (`supabase.com`) that trigger plugin installation prompts when pasted into chat. Set to `[]` or `false` to disable.

The catalog category is not set in plugin.json. The catalog packer derives it automatically from the parent category in marketplace.json.

Convention paths

Capabilities are added by placing files in standard convention directories:

Path	Capability
`mcp.json`	MCP servers
`skills/<name>/SKILL.md`	Skills
`rules/*.md`	Rules
`tools/*.ts`	Tools
`hooks/hooks.json`	Hooks
`agents/*.md`	Subagent definitions

You do not need to configure path fields in plugin.json for these locations. The packer discovers them automatically.

marketplace.json

The catalog index in reforma-ai/plugins uses marketplace.json to organize plugins into shelves and specify their source locations:

{
  "categories": [
    {
      "id": "backend",
      "name": "Backend",
      "plugins": [
        {
          "name": "my-plugin",
          "source": "./marketplace/backend/my-plugin"
        }
      ]
    }
  ]
}

Listing fields:

Field	Required	Description
`name`	Yes	Plugin slug. Must match the plugin's `plugin.json` name.
`source`	Yes	Local path (`./marketplace/<category>/<name>`) or pinned GitHub URL (`https://github.com/org/repo/tree/<commit>/<path>`).
`disabled`	No	Set to `true` to skip packing the plugin while preserving the listing.

Catalog overlays

For plugins maintained in external repositories, marketplace.json can override display metadata without modifying upstream sources:

{
  "name": "external-plugin",
  "source": "https://github.com/org/external-plugin/tree/v1.0.0",
  "displayName": "Custom Name",
  "description": "Customized catalog description.",
  "brandColor": "#1A1A1A"
}

Supported listing overlays include displayName, description, logo, logoSmall, brandColor, and agent.

Compatibility normalization

To support the broader ecosystem, the Reforma catalog packer automatically ingests and normalizes non-standard plugin layouts:

Input format	Normalized output
`.cursor-plugin`, `.codex-plugin`, `.claude-plugin`, `.reforma-plugin`	Root `plugin.json`
Custom paths in manifest	Canonical convention folders
Cursor `rules/*.mdc`, `.cursor/rules/`, `instructions/`	`rules/*.md`
`.mcp.json`	`mcp.json`
Source `tools/*.ts`	Bundled `tools.mjs`

Pack also discovers missing tool and resource metadata for HTTP MCP servers by performing a live probe during packing (stdio MCP servers are not probed).