Plugins Reference

Plugins are installable extension packages adding commands, Agents, Skills, Hooks, output styles, workflows, and MCP servers to Qoder CLI CN. This page is the complete reference for the plugin manifest, directory structure, and marketplace schema.

Plugin manifest (plugin.json)

The manifest file lives at .qoder-plugin/plugin.json; when that directory does not exist, .claude-plugin/plugin.json is read as a fallback. The manifest is not placed in the plugin root. The file can be omitted — without a declaration, the CLI loads components from the conventional directories and uses the plugin directory name as the plugin name; declaring it is recommended for stable metadata such as name and version.

Required fields

Only name is required in plugin.json; all other fields can be omitted.

Field	Type	Description
`name`	string	The plugin's unique identifier (kebab-case, no spaces).

Optional metadata fields

Field	Type	Description
`version`	string	Semantic version (such as `1.0.0`).
`displayName`	string	Human-friendly name shown in the UI.
`description`	string	A short description.
`author`	object	Author information (`name`/`email`/`url`).
`homepage`	string	Documentation or homepage URL.
`repository`	string	Source repository URL.
`license`	string	SPDX license identifier (such as `MIT`, `Apache-2.0`).
`keywords`	string[]	Search and categorization tags.
`dependencies`	array	Other plugins this one depends on (a marketplace can be specified).

Component declaration fields

The following fields override the conventional directories or declare components inline (relative-path strings, arrays, or object maps):

Field	Description
`commands`	Command definitions.
`agents`	Agent definition file paths.
`skills`	Skill directory paths.
`outputStyles`	Output style definitions.
`workflowsPath` / `workflowsPaths`	Workflow file paths.
`hooks`	Hook configuration (a relative-path JSON file or inline configuration).
`mcpServers`	MCP server configuration (a relative-path JSON file or inline configuration).
`userConfig`	User-configurable option definitions.
`settings`	Settings merged when the plugin is enabled. Currently only the `agent` key is supported; other keys are ignored.

Conventional directory structure

Without explicit component declarations in the manifest, a plugin is auto-discovered from these conventional directories:

plugin-name/
├── .qoder-plugin/
│   └── plugin.json      # Recommended: the manifest (omittable)
├── commands/            # Command definitions (.md)
│   └── subdir/          # Nested directories supported
├── agents/              # Agent definitions (.md)
├── skills/              # Skill directories
│   └── skill-name/
│       └── SKILL.md
├── hooks/
│   └── hooks.json       # Hook configuration
├── output-styles/       # Output style definitions
├── workflows/           # Workflow definitions
├── bin/                 # Executables (added to PATH)
└── .mcp.json            # MCP server configuration

mcp.json (without the leading dot) is accepted as a fallback for .mcp.json. When both exist, .mcp.json takes precedence, and they are not merged.

Marketplace manifest (marketplace.json)

A plugin marketplace describes a set of installable plugins via marketplace.json.

Required fields

Field	Type	Description
`name`	string	The marketplace name.
`owner`	object	Marketplace maintainer information (`name`/`email`/`url`).
`plugins`	array	The array of plugin entries.

Optional fields

Field	Type	Description
`forceRemoveDeletedPlugins`	boolean	Automatically uninstall plugins deleted from the marketplace.
`metadata.pluginRoot`	string	The base path relative to the plugin source.
`metadata.version`	string	The marketplace version.
`metadata.description`	string	The marketplace description.
`allowCrossMarketplaceDependenciesOn`	string[]	Marketplace names for which cross-marketplace dependencies are allowed.

Plugin entry fields

Field	Type	Description
`name`	string	The plugin name (must match `name` in `plugin.json`).
`source`	string/object	The plugin source (relative path, npm, git, github, url, etc.).
`category`	string	A category tag.
`tags`	string[]	Search tags.
`strict`	boolean	Whether a manifest must exist in the plugin folder (default `true`).

Management commands

In interactive sessions use /plugins (alias /plugin); without a subcommand it opens the plugin browser:

Subcommand	Parameters	Description
`install` (alias `i`)	`<plugin>`	Install a plugin.
`uninstall` (aliases `remove`/`rm`)	`<plugin>`	Uninstall a plugin.
`enable`	`<plugin>`	Enable a plugin.
`disable`	`<plugin>`	Disable a plugin.
`update`*	`<plugin>`	Update a plugin.
`marketplace` (alias `market`)*	—	Manage plugin marketplaces, with `add <source>`, `list`, `remove <name>`, `update [name]`.
`validate`	`<path>`	Validate a plugin directory or `plugin.json`.
`reload`	—	Reload all plugins.

On the command line use qodercn plugins (alias plugin):

Subcommand	Description
`list`	List installed plugins.
`install` (alias `i`)	Install a plugin from a marketplace or local directory.
`uninstall` (aliases `remove`/`rm`)	Uninstall a plugin.
`enable` / `disable`	Enable / disable a plugin.
`update`*	Update a plugin to the latest version from its source marketplace.
`validate`	Validate a plugin in a local directory.
`marketplace` (alias `mp`)*	Manage plugin marketplaces.

* Commands marked with an asterisk are governed by the plugin marketplace feature switch and are unavailable when it is off. Startup flag: --plugin-dir <path> adds an additional plugin search directory.

Security

These two settings live under the security group in settings.json (restart required after changes):

{
  "security": {
    "blockGitExtensions": true,
    "allowedExtensions": ["^https://github\\.com/my-org/"]
  }
}

security.blockGitExtensions: true blocks installing/loading plugins from Git.
security.allowedExtensions provides a regex allowlist of plugin sources; when non-empty, only matching sources are allowed (overriding blockGitExtensions).

Next steps

Plugin management commands: qodercn plugins --help.
Hooks reference: Hooks Reference.
MCP reference: MCP Reference.

​Plugin manifest (plugin.json)

​Required fields

​Optional metadata fields

​Component declaration fields

​Conventional directory structure

​Marketplace manifest (marketplace.json)

​Required fields

​Optional fields

​Plugin entry fields

​Management commands

​Security

​Next steps

Plugin manifest (plugin.json)

Required fields

Optional metadata fields

Component declaration fields

Conventional directory structure

Marketplace manifest (marketplace.json)

Required fields

Optional fields

Plugin entry fields

Management commands

Security

Next steps