How to Create Plugin Packages Using Manifest v1 in Reasonix

Manifest v1 plugin packages in Reasonix are self-contained directories that declare static contributions through a reasonix-plugin.json file at the root, requiring no runtime side-car or external processes to function.

The esengine/DeepSeek-Reasonix repository implements a dual-layer plugin architecture where Manifest v1 serves as the native format for pure-declarative extensions. This format allows developers to create plugin packages that expose skills, hooks, MCP servers, and themes without writing a single line of runtime code. When you create plugin packages using Manifest v1 in Reasonix, you define all capabilities statically in JSON, making the installation process lightweight and deterministic.

Understanding Manifest v1 Architecture

According to the source code in docs/PLUGIN_PACKAGES.md, Manifest v1 is the native format used for pure-declarative extensions. It contains no runtime block and therefore does not launch an out-of-process side-car. The internal parser located in internal/extension/manifest.go validates the reasonix-plugin.json file and rejects any missing or incorrect apiVersion fields.

The desktop client handles theme contributions through desktop/theme_plugin.go, while the core system manages skills, hooks, and MCP servers based on the manifest declarations. As documented in site/src/pages/docs.astro, plugin packages have two distinct layers: the static Manifest v1 layer and the optional runtime side-car layer (Manifest v2). For contrast, sdk/go/README.md demonstrates how Manifest v2 packages include a runtime block for side-car communication.

Setting Up the Plugin Directory Structure

A Manifest v1 package is a self-contained directory that serves as the sandbox for all relative paths. Reasonix treats the root directory as the boundary for all file references within the manifest.

Create a directory structure that organizes contributions by type:

my-plugin/
├── reasonix-plugin.json      # ← Manifest v1 descriptor

├── skills/
│   └── hello.skill          # Accessible via /my-plugin:hello

├── hooks/
│   └── session-start/
│       └── start.sh
└── mcpServers/
    └── helper/
        └── bin/
            └── helper       # Executable MCP server

Relative paths in the manifest point to sub-folders inside this root. Reasonix copies or links these files into its internal plugin storage, but does not execute any install scripts during the process.

Writing the reasonix-plugin.json Manifest

The reasonix-plugin.json file is the Manifest v1 descriptor. It must declare the exact reasonix.io/plugin/v1 version identifier and list static contributions including skills, hooks, mcpServers, and themes.

Below is the minimal schema structure supported by the parser:

{
  "name": "example",
  "version": "1.0.0",
  "description": "Example plugin",
  "skills": "skills",
  "hooks": {
    "SessionStart": [
      {
        "command": "hooks/session-start",
        "args": []
      },
      {
        "command": "printf 'ready' && ./hooks/audit",
        "shell": "bash"
      }
    ]
  },
  "mcpServers": {
    "helper": {
      "command": "bin/helper"
    }
  }
}

The hooks section supports both direct command execution and shell-specific commands using the "shell": "bash" parameter. The skills field points to the directory containing skill definitions, while mcpServers defines executable tools accessible through the normal tool flow.

Installing and Activating Plugins

Use the Reasonix CLI to install and manage Manifest v1 packages. The CLI validates the manifest before writing any files to the internal plugin storage and refuses to modify the filesystem unless explicit flags are provided.

Preview the installation plan without making changes:

reasonix plugin install /path/to/my-plugin --dry-run

Perform the installation with automatic confirmation:

reasonix plugin install /path/to/my-plugin --yes

For development workflows, use the --link flag to keep the folder live, allowing you to edit files and see changes without reinstalling:

reasonix plugin install /path/to/my-plugin --link --replace --yes

After installation, the plugin’s contributions become available automatically. Skills appear under /plugins/<name>:<skill> (for example, /my-plugin:hello), hooks fire on their lifecycle events, and MCP servers are reachable through the standard tool flow. No extra activation command is required.

Managing Plugin Lifecycle

Once installed, you can inspect, enable, disable, or remove Manifest v1 plugins using the CLI. Disabling stops the plugin’s contributions without removing its files from storage.

List all installed plugins:

reasonix plugin list

Show detailed information about a specific plugin:

reasonix plugin show my-plugin

Disable or re-enable a plugin:

reasonix plugin disable my-plugin
reasonix plugin enable my-plugin

Remove the plugin permanently:

reasonix plugin remove my-plugin --yes

The --yes flag is required for removal because the operation writes to the plugin storage, ensuring destructive actions are intentional.

Optional Compatibility Layers

If you want to support older Codex or Claude plugin formats simultaneously, add compatibility manifests to your package:

• .codex-plugin/plugin.json for Codex compatibility
• .claude-plugin/plugin.json for Claude compatibility

When present, the CLI reports compatibility status (full, partial, or none) during installation, allowing the same package to function across different AI coding platforms.

Summary

• Manifest v1 is the native, pure-declarative format for Reasonix plugins that requires no runtime side-car.
• Create a directory containing reasonix-plugin.json at the root and sub-folders for skills/, hooks/, mcpServers/, and themes/.
• The internal parser in internal/extension/manifest.go validates the manifest and rejects incorrect apiVersion fields.
• Install packages using reasonix plugin install with --dry-run for validation and --link for live development.
• Manage lifecycle through enable, disable, and remove commands, with --yes required for destructive operations.

Frequently Asked Questions

What is the difference between Manifest v1 and Manifest v2 in Reasonix?

Manifest v1 is a static, JSON-only format for pure-declarative extensions that contain no runtime block and do not launch out-of-process side-cars. Manifest v2, as shown in sdk/go/README.md, includes a runtime block that defines a side-car process for dynamic, stateful interactions. Choose Manifest v1 when your plugin only needs to expose static skills, hooks, and themes.

Can Manifest v1 plugins execute shell scripts?

Yes. The hooks section in reasonix-plugin.json supports shell execution by specifying the "shell" parameter (for example, "shell": "bash"). You can define multiple commands per lifecycle event, and each command can reference scripts stored in the plugin directory using relative paths.

How do I test a Manifest v1 plugin without reinstalling after every edit?

Use the --link flag during installation: reasonix plugin install /path/to/my-plugin --link --replace --yes. This creates a symbolic link to your development directory rather than copying files, allowing you to modify code and see changes immediately without re-running the install command.

Does Reasonix support compatibility with other AI plugin formats?

Yes. Reasonix can report compatibility with Codex and Claude plugin formats if you include .codex-plugin/plugin.json or .claude-plugin/plugin.json in your package root. The CLI evaluates these files during installation and reports whether the plugin offers full, partial, or none compatibility with those ecosystems.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}