# Organize Files

Use this skill when the user asks MoviePilot to identify and organize a local or...

- Repository: https://github.com/jxxghp/MoviePilot (12002 stars)
- Category: Media
- License: GPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add jxxghp/MoviePilot --skill organize-files -g -a claude-code -y`
Codex: `npx skills add jxxghp/MoviePilot --skill organize-files -g -a codex -y`
Cursor: `npx skills add jxxghp/MoviePilot --skill organize-files -g -a cursor -y`
Gemini CLI: `npx skills add jxxghp/MoviePilot --skill organize-files -g -a gemini-cli -y`

## Description

Use this skill when the user asks MoviePilot to identify and organize a local or downloaded video/music file, season folder, recording, album directory, or mixed folder that automatic transfer did not handle. If failed transfer history IDs are supplied, use transfer-failed-retry instead.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Organize Files

Use `moviepilot_api` for every MoviePilot business operation. Retired file,
recognition, transfer, and history tools are not available.

## Workflow

1. Establish scope. If the user provides a path, use it. If they identify a
   downloader task, use `downloader-operation` and its fixed
   `scripts/mp-downloader.py` helper to discover the instance and call
   `tasks.list`. If they only name a configured root, call `storage.settings`.
   Use `storage.list` to inspect the selected directory. Do not process a broad
   shared root without an explicit, bounded scope.
2. Classify files into movie, TV, one music recording, one complete album,
   subtitle/sidecar, or unrelated content. Do not group unrelated media merely
   because they share a directory.
3. Call `media.recognize` with the representative title or path. If uncertain,
   call `media.search`; if several exact candidates remain, use
   `ask_user_choice`. Never invent or translate an ID.
4. Preserve the exact `media_source` + `media_id`. For TV, verify season detail
   with `media.detail` when numbering is ambiguous. For music, a recording is one
   track, an album is one multi-track directory, and an artist is browse-only.
5. When duplicate risk matters, call `library.exists`. If an existing transfer
   record affects reorganization, inspect `transfer.history`.
6. Before a state-changing transfer, summarize the source, target identity,
   media type, season/music entity, storage, and mode. Continue only when the
   user's request already authorizes that exact action or after confirmation.
7. Call `transfer.file` once per verified unit. For an album, transfer the album
   directory once only after its supported audio-file count is consistent with
   the selected album detail.
8. If requested, call `media.scrape` after a successful transfer. Report actual
   tag, cover, and lyrics counts; never assume all lyrics were found.

## Structured Calls

The rest: https://github.com/jxxghp/MoviePilot/blob/HEAD/skills/organize-files/SKILL.md