/downloader-operation

name: downloader-operation
version: 3
description: >-
  Use this skill when the user asks to inspect, diagnose, or directly control a
  configured qBittorrent, Transmission, or rTorrent instance. It exposes
  provider capabilities on demand without adding permanent Agent tools, and is
  suitable for task files and selection, trackers, peers, queue order, limits,
  tags, locations, rechecks, direct provider submissions, or batch task control.
allowed-tools: execute_command

Downloader Operation

Use `scripts/mp-downloader.py`. The helper reads MoviePilot's local downloader configuration and credentials itself. Never request, print, or pass a host, username, password, API key, Cookie, or arbitrary URL.

Boundary

• Prefer `moviepilot-api` for ordinary MoviePilot acquisition workflows,

especially site search, `download.add`, subscriptions, transfer, history, and canonical library checks.

• Use this Skill for downloader-native inspection, diagnosis, advanced task

properties, and an explicit request to operate the provider directly.

• `tasks.add.direct` bypasses MoviePilot download history, site Cookie handling,

path selection, duplicate checks, and transfer orchestration. Use it only when the user explicitly wants direct provider submission.

• Paths passed to `tasks.location.set` and `tasks.add.direct` are downloader-side

paths, not MoviePilot storage paths.

• `tasks.location.set` is a raw provider operation and does not evaluate

MoviePilot media categories. For an existing MoviePilot task, use the Web UI resource-category preview and confirmation flow when the target should come from MoviePilot's download history and resource-directory rules.

Instance And Provider Discovery

Fast path: call directly

Do not routinely call `instances` or `capabilities` before an operation. This Skill already contains the full action contract, and the helper performs instance resolution, provider support checks, complete argument validation, and the action in one `call` invocation.

• If the user or prior context provides the exact client name, pass it with

`--client` and call the action immediately.

• If no client name is known, omit `--client`. The helper automatically uses the

single default downloader, or the only enabled downloader.

• If multiple clients remain ambiguous, the failed call lists every valid

client name. Reuse that list for the next direct call; do not add a separate `instances` call unless the user explicitly asks to inspect instances.

• Do not probe an action with empty or guessed arguments. Compose the complete

JSON object from the contract below before calling.

The helper rejects unknown fields and reports all detectable argument errors in one response before connecting to the provider, so correct every reported field together instead of retrying one field at a time.

Optional discovery

List configured instances without secrets:

python skills/downloader-operation/scripts/mp-downloader.py instances

List the actions supported by all providers or one configured client:

python skills/downloader-operation/scripts/mp-downloader.py capabilities
python skills/downloader-operation/scripts/mp-downloader.py capabilities --client "main-qb"

The complete action and argument contract is documented below. Use `capabilities` only to confirm which documented actions a configured provider supports. For a compact machine-readable copy of one action's same contract:

python skills/downloader-operation/scripts/mp-downloader.py capabilities \
  --client "main-qb" \
  --action tasks.properties.set

Do not inspect the helper source to discover arguments and do not guess a provider-specific action. `capabilities` is optional and should be used only when the configured provider itself is unknown or support must be diagnosed.

Call Shape

python skills/downloader-operation/scripts/mp-downloader.py call \
  --client "main-qb" \
  --action tasks.list \
  --arguments '{"status":"downloading","limit":20}'

The `--arguments` value must be one JSON object. Large reads are paged with `offset` and `limit`; the default limit is 50 and the maximum is 200.

External MCP Contract

External MCP clients do not receive this `SKILL.md` and cannot use the hidden `execute_command` tool. MoviePilot therefore exposes a separate admin-only MCP tool named `downloader_operation`. Its `tools/list` `inputSchema` contains one `oneOf` branch for every action below, including the function description, supported providers, effect, field types, required/default values, enums, and cross-field rules. The external client should select the matching branch and make one `tools/call`; it does not need to call a discovery tool first.

MCP call arguments use the same contract without shell quoting:

{
  "client": "main-qb",
  "action": "tasks.properties.set",
  "arguments": {
    "task_id": "exact-provider-hash",
    "download_limit": 2048,
    "upload_limit": 512
  }
}

`client` may be omitted for the default or only enabled downloader. If multiple instances remain ambiguous, the result lists the valid client names.

Complete Action Contract

This is the complete Downloader Operation action contract. It comes directly from the script `ACTIONS` registry and matches the external MCP `tools/list` oneOf branches. A field name ending in `*` is required. Put every action parameter in the `arguments` object.

| action | Purpose and argument summary | | :--- | :--- | | `capabilities.list` | List supported downloader actions and their complete argument contracts.; arguments: `action_name` | | `instances.list` | List configured downloader instances without connection secrets.; no arguments | | `session.content_layout` | Read qBittorrent's default torrent content layout.; no arguments | | `session.details` | Read Transmission session configuration and capacity details.; no arguments | | `session.speed_limits.get` | Read global speed lim