/create-moviepilot-plugin

name: create-moviepilot-plugin
version: 5
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: read_file write_file edit_file apply_patch execute_command search_web browse_webpage moviepilot_api
allowed-api-operations: config.system.get config.system.update plugin.market plugin.installed plugin.install plugin.reload

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/runtime/extensions/plugin_manager.py`

and `app/adapters/external/market.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, package entries, and directory contents.

• 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.

• Pick the editing tool by scope. Use `apply_patch` when one logical change

spans multiple files, adds new files, or deletes files: submit a single patch wrapped in `*** Begin Patch` / `*** End Patch` with `*** Add File:`, `*** Update File:`, and `*** Delete File:` sections; every context and removed line must match the current content exactly.

• Use `edit_file` for a single localized change in one file. 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 one standalone new file. 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.

• Read the structured command result: only `execution_outcome="succeeded"`

with `exit_code=0` means a completed command passed. Inspect `output` on failure and `output_file` for a truncated log. A timeout or unknown result does not undo side effects and must not trigger a blind retry of a write.

• For background commands, resume using both `output_until_seq` and

`output_until_offset` as `since_seq` and `since_offset`. Start with offset 0 for partial-chunk paging; `last_seq` is not a consumed position. Wait for new output in bounded intervals, and drain the remaining pages until `output_complete=true` for a complete log. Report any `output_lost` gap. An `output_error` after start/write/kill requires another read with a suitable byte limit, not another execution of the action.

• 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