/publish-moviepilot-plugin

name: publish-moviepilot-plugin
version: 6
description: >-
  Use this skill when the user asks to publish, upload, sync, pull, push, diff,
  or maintain a MoviePilot local plugin in a GitHub repository. Covers using the
  configured MoviePilot GitHub token, PLUGIN_LOCAL_REPO_PATHS local plugin
  repositories, package.json/package.v2.json/package.v3.json metadata,
  plugins/plugins.v2/plugins.v3
  layouts, safe file exclusion, diff preview before publishing, incremental
  GitHub Contents API updates, and syncing local plugin changes back from GitHub.
  Includes asking whether to use an existing repository or create a new public
  repository when no target repository is available.
  Also use for Chinese requests mentioning 插件发布, 插件维护, 推送插件到 GitHub,
  从 GitHub 拉取插件, 同步本地插件仓库, 增量发布插件, 插件仓库维护.
allowed-tools: read_file write_file edit_file apply_patch execute_command moviepilot_api
allowed-api-operations: config.system.get config.system.update

Publish MoviePilot Plugin

Use this skill to publish and maintain a MoviePilot local plugin repository through GitHub while protecting local secrets and unrelated plugins.

Scope

• Publish one local plugin under `plugins.v3/<plugin_id_lower>/`,

`plugins.v2/<plugin_id_lower>/` or `plugins/<plugin_id_lower>/` to a GitHub repository.

• Merge only that plugin's entry into `package.v3.json`, `package.v2.json` or

`package.json`.

• Preview local/remote differences before writing.
• Pull remote plugin files back to the local plugin source.
• Create the target GitHub repository when the user explicitly chooses automatic

creation; repositories are public by default unless the user asks for private.

• Reuse MoviePilot settings `GITHUB_TOKEN`, `REPO_GITHUB_TOKEN`,

and `PLUGIN_LOCAL_REPO_PATHS` when available.

Ground Truth

• Local plugin development rules: `skills/create-moviepilot-plugin/SKILL.md`.
• Local plugin source discovery: `app/adapters/external/market.py`,

`PluginHelper.get_local_repo_paths()`.

• GitHub token settings: `app/runtime/config.py`, especially `GITHUB_TOKEN` and

`REPO_GITHUB_TOKEN`.

• Plugin package layouts:
• V3: `package.v3.json` and `plugins.v3/<plugin_id_lower>/`
• V2: `package.v2.json` and `plugins.v2/<plugin_id_lower>/`
• Legacy: `package.json` and `plugins/<plugin_id_lower>/`

Pre-Flight

1. Identify the target plugin ID and local source repository.

• If the user gives a path, use it.
• Otherwise query `PLUGIN_LOCAL_REPO_PATHS`; if exactly one configured

repository contains the plugin, use it.

• If several configured repositories contain the plugin, ask which one.

2. Identify the GitHub repository as `owner/repo`.

• Use the user's explicit repository first.
• If omitted, infer only when the local source has an obvious Git remote.
• If neither is available, ask whether to use an existing repository or

automatically create a new public repository.

• If the user chooses an existing repository, ask for `owner/repo`.
• If the user chooses automatic creation, ask for the target `owner/repo`

and state that the repository will be public by default.

• Do not create a private repository unless the user explicitly asks for it.

3. Select the package version layout.

• Prefer `v3` when the plugin lives under `plugins.v3/<plugin_id_lower>/`

or the repository ships `package.v3.json` (current MoviePilot V3 hosts).

• Prefer `v2` when `package.v2.json` or `plugins.v2/<plugin_id_lower>/`

exists.

• Use legacy only when the local plugin is under `plugins/`.

4. Verify token availability.

• Prefer `REPO_GITHUB_TOKEN` for the target repo when configured.
• Fall back to `GITHUB_TOKEN`.
• If no token is configured, ask the user to configure one before pushing.

Read-only preview may still run without a token for public repositories.

Script

Use `scripts/publish_plugin.py` for deterministic GitHub operations.

python skills/publish-moviepilot-plugin/scripts/publish_plugin.py preview \
  --repo owner/repo \
  --plugin-id MyPlugin \
  --local-repo /path/to/MoviePilot-Plugins \
  --package-version v2

python skills/publish-moviepilot-plugin/scripts/publish_plugin.py push \
  --repo owner/repo \
  --plugin-id MyPlugin \
  --local-repo /path/to/MoviePilot-Plugins \
  --package-version v2 \
  --message "Publish MyPlugin v1.0.0"

python skills/publish-moviepilot-plugin/scripts/publish_plugin.py pull \
  --repo owner/repo \
  --plugin-id MyPlugin \
  --local-repo /path/to/MoviePilot-Plugins \
  --package-version v2

# V3 插件仓库（package.v3.json + plugins.v3/）
python skills/publish-moviepilot-plugin/scripts/publish_plugin.py push \
  --repo owner/repo \
  --plugin-id MyPlugin \
  --local-repo /path/to/MoviePilot-Plugins \
  --package-version v3 \
  --message "Publish MyPlugin v1.0.0"

python skills/publish-moviepilot-plugin/scripts/publish_plugin.py create-repo \
  --repo owner/repo

Options:

• `--package-version v3|v2|legacy|auto`: layout selector. `auto` resolves the

layout from where the plugin directory actually lives (`plugins.v3` → `plugins.v2` → `plugins`), then falls back to the manifest files, so repositories that still keep both manifests stay correct. Pass `v3` explicitly for current MoviePilot V3 plugin repositories.

• `create-repo`: create the target GitHub repository. Default visibility is

public; use `--private` only when the user explicitly asked for private.

• `preview`: compare local filtered files with remote files and print JSON.
• `push`: upload changed files and merge the plugin package entry.
• `pull`: write remote plugin files and package entry into local source.
• `--create-repo-if-missing`: on push, create the target public repository when

GitHub reports that it does not exist.

• `--delete-remote`: on push, delete remote plugin files that no longer exist

locally after exclusions.

• `--force`: on pull, allow overwriting local files that differ from remote.
• `--include PATTERN`: add files otherwise excluded b