/create-moviepilot-plugin

name: create-moviepilot-plugin
version: 7
description: >-
  Use this skill when the user asks to create, modify, debug, validate, or
  scaffold a MoviePilot local plugin. Covers version-aware V3/V2 plugin development,
  _PluginBase implementations, package.v3.json/package.v2.json/package.json metadata,
  plugins.v3/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, get_agent_pets assistant avatars, commands, services, workflow actions, agent tools, and local
  install/reload flows. Also use for Chinese requests mentioning 编写插件、本地插件源,
  插件开发, V3插件, 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`.
• First identify the actual host generation from its source/version and the

target plugin repository. MoviePilot V3 uses `plugins.v3/` with `package.v3.json`; V2 uses `plugins.v2/` with `package.v2.json`; legacy V1 uses `plugins/` with `package.json`. Do not generate V2 paths for a V3 host.

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

`docs/Repository_Guide.md`, and the guide for the target generation: `docs/Plugin_Development.md` for V3, `docs/V2_Plugin_Development.md` for V2. For scenario-specific extensions, read the matching `docs/faq/*.md`.

• For V3, prefer the public `app.sdk.*` entry points documented by the current

host and guide; do not copy old internal imports from a V2 example. Verify extension signatures against the installed host before using a template.

Task Scope

A request to create or fix a plugin authorizes relevant local source edits and validation. Reuse that authorization; it does not by itself authorize changing host configuration, installing/reloading the plugin, restarting, or publishing. Perform those steps when the user requested them or already approved their scope, honoring host confirmation requirements. Inspect auto-reload settings before editing a live watched plugin source; such edits can affect the runtime immediately and require that runtime effect to be within the authorized scope.

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