> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish & Use

After developing your plugin, the final step is to publish it to npm and enable it in the host system (Xpert AI).

## Publish Plugin

Run the following commands in the monorepo root directory:

```bash theme={null}
# Build the plugin
npx nx build my-plugin

# Use the monorepo's release workflow
npx nx release

# Or manually publish to npm
npx nx run @xpert-ai/my-plugin:nx-release-publish --access public --otp=<one-time-password-if-needed>
```

Once published, you'll get an installable package on npm, for example:

```
@xpert-ai/my-plugin
```

## Use Plugin

In the Xpert AI host system, declare the list of enabled plugins using the `PLUGINS` environment variable. Separate multiple plugins with commas:

```bash theme={null}
PLUGINS=@xpert-ai/my-plugin1,@xpert-ai/my-plugin2
```

When the host starts, it will automatically parse the `PLUGINS` environment variable and load these plugins in order.

**Notes**:

* The host project should install the plugin packages via npm/yarn/pnpm (`npm install @xpert-ai/my-plugin`) and configure the plugin list in the environment variable.
* The plugin's `meta.name` must match the npm package name.
* If a plugin fails to load correctly, check the logs for `register` or `onPluginBootstrap` output.
* After starting the Xpert AI system, you can view the loaded plugins on the system settings [Plugins page](https://app.xpertai.cn/settings/plugins).

## Installation Scope

Installed plugins have an explicit scope:

* **Organization plugins** are installed into the current organization and can be managed from that organization.
* **Tenant-global plugins** are shared by all organizations in the current tenant.
* **System plugins** declare `meta.level = 'system'` and are installed once for the whole platform under `system:global`.

System plugins are platform singletons. They can be installed or updated only by a Super Admin in the Default tenant. Other tenants may see and use the capabilities provided by system plugins, but they cannot install, uninstall, or configure the system instance from their own organization or tenant view.

At runtime, the platform resolves plugin capabilities in this order:

```text theme={null}
organization -> tenant-global -> system-global -> built-in
```

So tenant or organization plugins can intentionally override a system default without creating a second system instance.

## Initialize Plugin Resources

Loading a plugin into the host is only the first step. The host can also initialize the resources declared inside the plugin bundle into the target runtime.

On the Plugins page, the installed plugin card exposes a resource initialization action. Opening it launches a dialog that reads the current bundle definitions live, rather than relying on a stale cached list.

Resources are split into two targets:

* **Workspace**: initialize into a workspace for `Skills`, `MCP`, and `Apps`
* **Xpert**: initialize into an existing Xpert for `Hooks`

The dialog groups resources by type and shows their current state:

* Already initialized resources are marked as installed and cannot be selected again
* If the plugin bundle changes, the dialog can surface stale definitions as updateable resources
* `assets/` are bundle metadata and presentation assets, not installable resources

After initialization, the host binds the resource to the actual runtime object and updates the corresponding middleware, toolset, or connector state in the workspace or Xpert.