/create-moviepilot-plugin

name: create-moviepilot-plugin
version: 3
description: >-
  Use this skill when the user asks to create, modify, debug, validate, or
  scaffold a MoviePilot local plugin. Covers MoviePilot V2 plugin development,
  _PluginBase implementations, package.v2.json/package.json market metadata,
  plugins.v2/plugins source layout, PLUGIN_LOCAL_REPO_PATHS local plugin
  sources, plugin APIs, Vuetify JSON forms/pages/dashboards, Vue module
  federation remote components, get_render_mode, get_sidebar_nav, plugin
  sidebar pages, commands, services, workflow actions, agent tools, and local
  install/reload flows. Also use for Chinese requests mentioning 编写插件、本地插件源,
  插件开发, V2插件, 插件市场, 本地安装插件, 插件热加载, 前端联邦, 侧栏入口, Vue插件页面.
allowed-tools: list_directory read_file write_file edit_file execute_command search_web browse_webpage query_system_settings update_system_settings query_market_plugins install_plugin reload_plugin query_installed_plugins

Create MoviePilot Plugin

Use this skill to build or revise MoviePilot plugins that can be developed from a local plugin source and installed into the running MoviePilot instance.

Ground Truth

• Host plugin contract: `app/plugins/__init__.py`, especially `_PluginBase`.
• Host plugin discovery, local source sync, install, reload: `app/core/plugin.py`

and `app/helper/plugin.py`.

• Host plugin endpoints, API auth, static files, remotes, and sidebar nav:

`app/api/endpoints/plugin.py`.

• Local development note: `docs/development-setup.md`.
• Plugin repository conventions: `MoviePilot-Plugins` uses `plugins.v2/` with

`package.v2.json` for V2 plugins; legacy or cross-generation entries may use `plugins/` with `package.json`.

• When working in or from `MoviePilot-Plugins`, read its `README.md`,

`docs/Repository_Guide.md`, and `docs/V2_Plugin_Development.md`. For scenario-specific extensions, read the matching `docs/faq/*.md`.

Code Tool Workflow

• Use `execute_command(action="run")` with `rg` and narrow globs or paths to

locate plugin classes, extension points, tests, and package entries. Use `list_directory` only when inspecting one known folder or a configured remote storage backend.

• Read the relevant implementation and adjacent example before editing.
• If `read_file` reports truncation, continue with smaller `start_line` and

`end_line` ranges until all relevant sections have been inspected.

• Before using a Python or Node.js dependency API, determine the exact installed

or locked version from requirements, package manifests, lockfiles, local package source, and `.pyi`/`.d.ts` declarations. If those are insufficient, use `search_web` with the official documentation domain and `browse_webpage` to read the matching version. Do not guess API signatures from memory or mix examples from different major versions. Search the relevant package directory, `.venv`, or `node_modules` directly with `rg` instead of scanning the entire project without bounds.

• Use `edit_file` for localized changes. Its `old_text` must identify one exact

location by default; add surrounding context instead of enabling `replace_all` unless every match intentionally changes.

• Use `write_file` for new files. Existing files require `overwrite=true` for a

full rewrite; first call `read_file(include_metadata=true)` and pass its `sha256` as `expected_sha256` when replacing previously read content.

• Use `execute_command(action="run")` for short validation, Git, and diagnostic

commands. Use `action="start"` only for interactive or long-running commands, then continue through the returned session ID.

• Do not use shell redirection or inline scripts to perform source edits or to

bypass a file-tool permission error.

• When the plugin uses Vue federation, also read

`MoviePilot-Frontend/docs/module-federation-guide.md`, `MoviePilot-Frontend/docs/federation-troubleshooting.md`, `MoviePilot-Frontend/src/utils/federationLoader.ts`, and `MoviePilot-Frontend/src/pages/plugin-app.vue`.

• Repository boundaries: `MoviePilot` owns runtime loading, API registration,

events, services, data, and permissions; `MoviePilot-Frontend` owns plugin UI rendering, federation loading, and sidebar pages; `MoviePilot-Plugins` owns plugin source, icons, package indexes, and release metadata.

Pre-Flight

1. Understand the user request: plugin purpose, trigger mode, configuration, output UI, whether it needs a scheduler, API, command, workflow action, or agent tool. 2. Run the UI Mode Selection Gate before writing any UI code.

• If the user already explicitly chose JSON config/Vuetify JSON or Vue

federation, follow that choice.

• If the plugin has any UI surface and the user has not chosen a mode, ask

them to choose between the two modes below and wait for the answer before implementing UI files or schemas.

• Do not silently default to either mode just because one seems easier.

3. Inspect existing plugins before creating a new one:

• Local runtime examples: `app/plugins/<plugin>/__init__.py`
• Market/local source candidates: use `query_market_plugins` when the

running instance is available.

• Installed plugin candidates: use `query_installed_plugins`; its summaries

include `repo_url` when the source can be matched from a local plugin repository or plugin market metadata.

• For Vue federation examples, prefer current compliant plugins such as

`MoviePilot-Plugins/plugins.v2/agenttokens/` and the frontend example `MoviePilot-Frontend/examples/plugin-component/`. 4. Determine the target source path:

• Query `PLUGIN_LOCAL_REPO_PATHS` with `query_system_settings` when possible.
• If exactly one local plugin repository is configured, prefer that path.
• If several are configured, choose the one the user named; otherwise ask

which repository to use.

• If none is configured, set it before writing plugin code:

`update_system_settings(setting_key="PLUGIN_LOCAL_REPO_PATHS", valu