Skip to content

About

AI agent Skill to organize TV Shows into folders for Jellyfin/ Plex media servers

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

TV Show Library Organizer

skills.sh

An AI agent skill that sorts a TV show library into a Jellyfin/Plex-friendly Show Name/Season N/ layout. It moves episode videos out of per-release download folders (e.g. My.Show.S02E07.MULTi.1080p.WEB.H264-Group/x.mkv) into the correct season folder, deriving the show and season from file or folder names, matching existing show folders case- and punctuation-insensitively, and staying safe to re-run.

Table of Contents

Background

TV episodes usually arrive in per-release folders whose names encode the episode (Some.Show.S02E07.MULTi.1080p.WEB.H264-Group/), while Jellyfin and Plex expect a flat Show Name/Season N/ layout. Doing this by hand is tedious, and asking an agent to improvise the moves one file at a time is slow and error-prone — it has to re-derive the same parsing and folder-matching rules for every batch.

This skill packages that logic as a single deterministic Bash script and gives the agent the operating procedure around it: dry-run first, confirm the plan, then execute and verify. The parsing rules come from real release naming conventions (dot/underscore/space-separated SxxEyy, 2x07 style, years in names) rather than from the model's guesswork, so the same input always produces the same layout.

Philosophy

  • Safe by default. The only correct first move is --dry-run. Nothing is moved until a human (or an explicit instruction) confirms the plan, and the script never overwrites an existing file.
  • Idempotent. Running it twice is a no-op the second time — files already in a Season N folder are skipped, so it can be re-run safely after partial failures.
  • Do one thing. It sorts TV episodes into season folders. It does not fetch metadata, rename files to a canonical scheme, or touch movies.
  • Deterministic. Show and season are parsed from file/folder names with explicit patterns; there is no fuzzy AI guessing about where a file belongs.

Features

The skill covers the whole flatten-and-sort workflow. The tool behind it is the bundled Bash script organize-shows.sh.

Capability What it does
Release-folder flattening Moves the video out of a per-episode release folder into Season N, then removes the now-empty folder
Loose-file sorting Episode files sitting directly in a show folder are placed into the right Season N subfolder
Name parsing S02E07 / s02e07 / S2E7 (dot, underscore, or space separated) and 2x07 style; falls back to the parent folder name when the file name has no episode token
Year stripping Trailing year tokens are dropped from the show name (My.Show.2008.S01E01… → My Show; Some Show (2025) S01E01… → Some Show)
Folder matching Existing show folders are matched exactly, then normalized (lowercase, punctuation/apostrophes removed, standalone year tokens dropped) — so Some Show (2025) lands in an existing Some Show 2025 folder instead of creating a near-duplicate
Dry-run --dry-run (or -n) prints every planned source -> destination move and changes nothing
Skip rules Files already in a Season N folder, files whose destination exists, and files with sample in the name are skipped; unparseable names are reported as SKIP and left in place

Scope: TV episodes only, in .mkv .mp4 .m4v .avi .ts .webm .wmv .mov, scanned to a depth of 3 under the library root. Metadata lookup, canonical file renaming, and movie libraries are out of scope.

Installation

This is an agent skill, not a package. Install it into the AI tool you use, and make sure the script's runtime requirements are met wherever the library lives:

  • Linux with bash, GNU find, and GNU sed (the script targets GNU sed 4.x; BSD/macOS sed may fail on \b and \xHH escapes).
  • Write access to the library directory. Moves are same-filesystem renames.

The skill follows the standard SKILL.md convention: the agent discovers a directory containing a SKILL.md with name/description frontmatter and loads it when the description matches the task.

skills.sh (recommended)

Install with the skills.sh CLI — it works with Claude Code, Codex, Cursor, Kimi Code CLI, and 70+ other agents, installing to each tool's skills directory automatically:

npx skills add blodberg/TvShowOrganizerSkill --skill tv-show-library-organizer

Add -g to install globally (available in every project) instead of into the current project, and -y to skip the confirmation prompts. See the skills.sh CLI docs for all options.

Manual install

If your agent isn't supported by the CLI, copy (or symlink) the skill files into its skills directory yourself, keeping SKILL.md and organize-shows.sh together in the same folder:

  1. Clone this repository:

    git clone https://github.com/blodberg/TvShowOrganizerSkill.git
  2. Copy or symlink the skill into your agent's skills directory. For agents that use ~/.agents/skills/ (adapt the path to your tool, e.g. ~/.claude/skills/):

    mkdir -p ~/.agents/skills/tv-show-library-organizer
    cp TvShowOrganizerSkill/SKILL.md TvShowOrganizerSkill/organize-shows.sh \
       ~/.agents/skills/tv-show-library-organizer/
    chmod +x ~/.agents/skills/tv-show-library-organizer/organize-shows.sh
  3. Start a new agent session and confirm the skill loaded by asking the agent to list its available skills — tv-show-library-organizer should appear.

Scope note: user-level (~/.agents/skills/) makes the skill available in every session; project-level (.agents/skills/ inside a repo) limits it to that project. There is no configuration, no API key, and no network access.

Usage

The skill activates when a task involves organizing a TV library: per-release episode folders that need flattening, loose episode files that need season subfolders, or a mix — including shows that don't have a folder yet. Most agents pick it up from the task itself. You can also name it:

Use the tv-show-library-organizer skill to sort the shows in /mnt/media/Shows.

SKILL.md is the router. It tells the agent to:

  1. Dry-run first — run ./organize-shows.sh --dry-run against the library root (the folder containing the show folders, not an individual show) and show the planned moves.
  2. Confirm the planned destinations before touching a live library.
  3. Execute the real run, then verify by re-running with --dry-run — it should report Moved: 0, skipped: 0.

If you want to run the script yourself instead of through an agent:

# 1. Always dry-run first and inspect the planned moves:
./organize-shows.sh --dry-run

# 2. If the plan looks right, run for real:
./organize-shows.sh

# Organize a different library root (default is the script's own directory):
./organize-shows.sh /path/to/other/Shows

# -n is shorthand for --dry-run; -h prints usage.

Troubleshooting

  • sed: unterminated 's' command — you are on BSD/macOS sed. Install GNU sed (brew install gnu-sed, then use gsed) or run on Linux.
  • A show got a new folder instead of matching an existing one — check the dry-run output; if names differ only by punctuation/year it should have matched. Report the pair of names as a bug.
  • Episodes sorted into the wrong season — the name likely contains another S<digits>E<digits>-like token earlier than the real one; rename the file so the episode token is unambiguous.

Project Structure

TvShowOrganizerSkill/
├── SKILL.md              # Skill definition: trigger conditions, usage, agent guidelines
├── organize-shows.sh     # The organizer script (Bash, GNU find/sed)
├── LICENSE               # MIT License
└── README.md

Contributing

Contributions are welcome. When changing the script:

  • Keep it safe by default — any behavior change must preserve the dry-run-first flow, the never-overwrite rule, and idempotency.
  • Keep SKILL.md in sync with the script — it documents the exact naming patterns, skip rules, and troubleshooting notes agents rely on, so behavior changes need matching skill-file updates.
  • Run ./organize-shows.sh --dry-run on a fixture tree before and after; a second run on an organized tree must report Moved: 0, skipped: 0.
  • Example names in docs stay generic; no real show names.

License

Released under the MIT License.

About

AI agent Skill to organize TV Shows into folders for Jellyfin/ Plex media servers

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

⌂ 换网址