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.
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.
- 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 Nfolder 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.
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.
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, GNUfind, and GNUsed(the script targets GNU sed 4.x; BSD/macOS sed may fail on\band\xHHescapes). - 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.
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-organizerAdd -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.
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:
-
Clone this repository:
git clone https://github.com/blodberg/TvShowOrganizerSkill.git
-
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
-
Start a new agent session and confirm the skill loaded by asking the agent to list its available skills —
tv-show-library-organizershould 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.
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:
- Dry-run first — run
./organize-shows.sh --dry-runagainst the library root (the folder containing the show folders, not an individual show) and show the planned moves. - Confirm the planned destinations before touching a live library.
- Execute the real run, then verify by re-running with
--dry-run— it should reportMoved: 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.sed: unterminated 's' command— you are on BSD/macOS sed. Install GNU sed (brew install gnu-sed, then usegsed) 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.
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
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.mdin 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-runon a fixture tree before and after; a second run on an organized tree must reportMoved: 0, skipped: 0. - Example names in docs stay generic; no real show names.
Released under the MIT License.