# How to Create Plugin Packages Using Manifest v1 in Reasonix

> Learn to create plugin packages in Reasonix using Manifest v1. Discover how these self-contained directories declare static contributions via a reasonix-plugin.json file.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-08-08

---

**Manifest v1 plugin packages in Reasonix are self-contained directories that declare static contributions through a [`reasonix-plugin.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/extension/manifest.go) validates the [`reasonix-plugin.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix-plugin.json) file and rejects any missing or incorrect `apiVersion` fields.

The desktop client handles theme contributions through [`desktop/theme_plugin.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```text
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```json
{
  "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:

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

```

Perform the installation with automatic confirmation:

```bash
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:

```bash
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:

```bash
reasonix plugin list

```

Show detailed information about a specific plugin:

```bash
reasonix plugin show my-plugin

```

Disable or re-enable a plugin:

```bash
reasonix plugin disable my-plugin
reasonix plugin enable my-plugin

```

Remove the plugin permanently:

```bash
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.codex-plugin/plugin.json) for Codex compatibility
- [`.claude-plugin/plugin.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix-plugin.json) at the root and sub-folders for `skills/`, `hooks/`, `mcpServers/`, and `themes/`.
- The internal parser in [`internal/extension/manifest.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.codex-plugin/plugin.json) or [`.claude-plugin/plugin.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.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.