Plugin files

Every field of plugin.json and marketplace.json that Multilo reads, where a plugin's parts can live, and the variables it fills in.

This page is the reference for plugin authors. For a walk-through of making and sharing a plugin, see Publishing skills. For installing plugins, see Plugins.

Multilo reads the same plugin format as other agent tools, so a plugin made for them usually works here unchanged.

Where the files go

File	Location
`plugin.json`	`.multilo-plugin/plugin.json` in the plugin’s folder. `.claude-plugin/plugin.json` is read if there’s no `.multilo-plugin/` one. Optional.
`marketplace.json`	`.multilo-plugin/marketplace.json` at the top of the marketplace’s repository or folder, or `.claude-plugin/marketplace.json`. Required for a marketplace.

Both files are JSON, up to 256 KB. A plugin can be up to 50 MB and 2,000 files.

plugin.json

Field	What it is
`name`	The plugin’s name. Lowercase letters, numbers and dashes, up to 64 characters. Its parts are named `<name>:<part>`.
`version`	The plugin’s version. Multilo installs a plugin again when its version changes, so raise it with every release. Without one, the marketplace’s version is used, then `latest`.
`description`	One line about what the plugin does.
`author`	`{ "name": "…" }`
`skills`	Extra skill folders, as a path or a list of paths. Adds to `skills/`.
`commands`	Command files or folders, as a path, a list, or a map. Replaces `commands/`.
`agents`	Agent files, as a path or a list of `.md` files (not folders). Replaces `agents/`.
`hooks`	Hooks, as a path to a hooks file, an inline object, or a list of both. Merges with `hooks/hooks.json`.
`mcpServers`	MCP servers, as a path to an MCP file, an inline object, or a list of both. Merges with `.mcp.json`; for the same server name, the later one wins.

Not read yet: userConfig, lspServers, outputStyles, dependencies, and .mcpb bundles named in mcpServers, which are listed under Errors.

Default locations

Without any of the fields above, a plugin’s parts are read from:

my-plugin/
  .multilo-plugin/plugin.json
  skills/<name>/SKILL.md
  commands/<name>.md
  agents/<name>.md
  hooks/hooks.json
  .mcp.json

A plugin that is a single skill can be just a SKILL.md at its root, with no skills/ folder and no skills field. The skill takes the plugin’s name.

Paths

Every path starts with ./ and is relative to the plugin’s folder. In skills, . means the plugin’s root.
A path can’t leave the plugin’s folder, and it must exist.
A path that breaks these rules doesn’t load. It’s listed under Errors in Settings › Customize › Plugins with the reason, for example skills path must be a folder.
When commands or agents is set and the default folder also exists, the default folder is ignored and a warning says so.

Commands as a map

commands can name each command, with either a source file or inline content (exactly one of them):

"commands": {
  "summarize": { "source": "./prompts/summarize.md", "description": "Summarize the open document" },
  "outline": { "content": "Write an outline of the open document.", "description": "Outline the open document" }
}

Each entry can also set description, argumentHint, model and allowedTools, which override the file’s own front matter. Command names are lowercase letters, numbers, ., _ and -, up to 64 characters.

Hooks and MCP files

A hooks file has a top-level "hooks" object. An inline hooks value in plugin.json is that object itself.
An MCP file is a { "mcpServers": { … } } map, or the server map on its own.

Hooks and MCP servers from a plugin run only after the person approves each one. See Plugins.

Variables

Multilo fills these in the plugin’s skill, command and agent text, its hook commands and its MCP server settings. Hook and MCP processes also get them in their environment.

Variable	Value
`${CLAUDE_PLUGIN_ROOT}`	The plugin’s installed folder
`${CLAUDE_PLUGIN_DATA}`	A folder for the plugin’s own data. It’s kept across updates, made on first use, and removed when the plugin is uninstalled.
`${CLAUDE_PROJECT_DIR}`	The open project’s folder

marketplace.json

{
  "name": "acme-tools",
  "owner": { "name": "Acme Lab" },
  "plugins": [
    { "name": "lab-notebook", "source": "./plugins/lab-notebook", "description": "Keep a lab notebook", "version": "1.2.0", "category": "research", "author": { "name": "Acme Lab" } }
  ]
}

Field	What it is
`name`	Required. The marketplace’s name: lowercase letters, numbers and dashes, up to 64 characters. Names starting with `multilo` are reserved.
`owner.name`	Who maintains it.
`plugins`	The list of plugins. Each entry has `name` (required, the same rules as a plugin name), `source` (required), `description`, `version`, `category` and `author.name`. Entries with an invalid name are skipped.

A plugin’s ID is <plugin>@<marketplace>, for example lab-notebook@acme-tools.

Plugin sources

`source`	Where the plugin comes from
`"./path"`	A folder inside the marketplace’s own repository or folder. The path can’t leave the marketplace.
`{ "source": "github", "repo": "owner/repo" }`	A GitHub repository. Optional `ref` (a branch or tag) and `path` (a folder inside it).
`{ "source": "url", "url": "…" }`	A git repository by its URL (`https://` or ssh). Optional `ref` and `sha` to pin a commit. Git must be installed for repositories outside GitHub.
`{ "source": "git-subdir", "url": "…", "path": "…" }`	A folder inside a git repository, with the same options as `url`.

Any other source type is listed as not supported yet.

Versions and updates

For a plugin inside the marketplace, the version is its plugin.json version, else the marketplace entry’s.
For a plugin in another repository, only the marketplace entry’s version is used to spot updates, so raise it there too.

Multilo updates a plugin when the version changes: when someone clicks Update, or at startup when auto-update is on for that marketplace.

Troubleshoot

Message	What it means
“No .multilo-plugin/marketplace.json or .claude-plugin/marketplace.json there.”	The repository or folder has no marketplace file in either place.
“… marketplace.json is not valid JSON.”	Fix the JSON syntax.
“The marketplace has no valid name.”	`name` is missing or has characters other than lowercase letters, numbers and dashes.
“This plugin’s source type (…) is not supported yet.”	Use a path, `github`, `url` or `git-subdir` source.
“The plugin’s path leaves its marketplace.”	A `"./…"` source uses `..`. Keep plugins inside the marketplace.
“A plugin’s git URL must be https:// or ssh.”	Use an `https://`, `ssh://` or `git@host:` URL.
A path error under Errors, such as “skills path must be a folder”	See Paths.

Publishing skillsMake a plugin and share it.PluginsInstall and manage plugins.HooksThe hooks file format.MCPMCP server settings.