Game Cover Downloader

中文文档

A CLI tool for batch downloading game covers, logos, title screens, and screenshots from the Libretro Thumbnail Library. Features fuzzy ROM filename matching, multi-threaded downloads, frontend layout presets (Pegasus / ES-DE / RetroArch), and custom save rules.

When used as an AI coding assistant Skill, you can drive downloads with natural language — no need to memorize CLI arguments.

📺 Retro Gamer's Blessing: AI Skill for One-Click Classic Game Cover Downloads

Features

• 🎮 Download covers by game name, single ROM file, or ROM folder
• 🔍 Fuzzy match ROM filenames against the Libretro game database
• 🖼️ Four media types: Boxarts, Logos, Titles, Snaps
• 📁 Built-in presets for Pegasus / ES-DE / RetroArch / Simple layouts
• ✏️ Custom save rules (JSON format), with save-as-preset for reuse
• 🚀 Default 4-thread downloads, configurable to higher thread counts
• 🔄 Two-stage recovery for unmatched ROMs (web search for No-Intro names)
• 📊 JSON output with progress events and download reports

Requirements

• Python 3.10+
• requests

Installation

1. Install Python dependencies

pip install -r requirements.txt

2. Download game database

The libretro_data/ directory (~400 MB) contains the game name database and is not included in the Git repository. Download it with the included script:

python fetch_data.py

This will automatically download and extract libretro_data.zip from the repository.

If fetch_data.py doesn't work, you can manually download libretro_data.zip from the repository and extract it to the project root.

Make sure the final structure looks like this (avoid nested libretro_data/libretro_data/):

game-cover-downloader-skill/
  libretro_data/         ← this folder must be directly under the project root
    mediadata/
    metadata/
    merged_games.json
    platform-aliases.json

Wrong ❌:

game-cover-downloader-skill/
  libretro_data/
    libretro_data/       ← nested! drag the inner folder up one level
      mediadata/

Quick Start

As an AI Skill (Natural Language)

When installed as a Skill, just describe what you want in your AI coding assistant's chat:

CLI Usage

# Download a single game's cover
python -m scripts.cover_cli download-game --name "Super Mario Bros." --system "Nintendo - Nintendo Entertainment System" --output "./covers"

# Download a single ROM file's cover
python -m scripts.cover_cli download-file --path "F:\Roms\gbc\Zelda.zip" --output "./covers"

# Download all GBC game covers from a ROM folder
python -m scripts.cover_cli download-folder --path "F:\Roms\gbc" --system "Nintendo - Game Boy Color" --output "F:\Roms\gbc\download"

# Same as above, with ES-DE layout and cover+logo
python -m scripts.cover_cli download-folder --path "F:\Roms\gbc" --system "Nintendo - Game Boy Color" --output "F:\Roms\gbc\download" --type boxarts,logos --preset es-de

Using Preset Layouts

# Pegasus: each game gets its own folder with boxFront.png, logo.png, etc.
python -m scripts.cover_cli download-folder --path "F:\Roms\fc" --system "Nintendo - Nintendo Entertainment System" --output "F:\Roms\fc\media" --type boxarts,logos --preset pegasus

# ES-DE: covers/, marquees/, titlescreens/, screenshots/ subdirectories
python -m scripts.cover_cli download-folder --path "F:\Roms\gbc" --system "Nintendo - Game Boy Color" --output "F:\Roms\gbc\download" --type boxarts,logos --preset es-de

# RetroArch: Named_Boxarts/, Named_Logos/, etc. with matched game names
python -m scripts.cover_cli download-folder --path "F:\Roms\n64" --system "Nintendo - Nintendo 64" --output "F:\Roms\n64\thumbnails" --type all --preset retroarch

# Simple: all covers directly in the output folder
python -m scripts.cover_cli download-folder --path "F:\Roms\snes" --system "Nintendo - Super Nintendo Entertainment System" --output "F:\Roms\snes\covers" --preset simple

List Available Presets

python -m scripts.cover_cli list-presets

Save a Custom Preset

python -m scripts.cover_cli save-preset --name "my-n64" --rule '{"Named_Boxarts":{"dir":"{output}/{rom}","name":"boxfront"},"Named_Logos":{"dir":"{output}/{rom}","name":"logo"}}' --filename rom --desc "N64: ROM-name folders with type-alias filenames"

Installing as an AI Coding Assistant Skill

This tool follows the Agent Skills standard. The SKILL.md is compatible with all AI coding clients that support this standard. Simply place the project folder into the corresponding client's skills directory — no extra configuration needed.

Client Installation Paths

Windows users: ~ corresponds to %USERPROFILE%, e.g. C:\Users\YourName\.claude\skills\game-cover-downloader-skill\

Installation Steps

Option 1: Git Clone (Recommended)

# Example for Claude Code — replace the path for other clients
git clone https://github.com/wang1025475397/game-cover-downloader-skill.git ~/.claude/skills/game-cover-downloader-skill

Option 2: Manual Copy

1. Download and extract the project ZIP
2. Copy the entire game-cover-downloader-skill folder to the client's skills directory from the table above
3. Ensure the directory structure is <skills-path>/game-cover-downloader-skill/SKILL.md

Option 3: Project-level Install (Team Sharing)

Place the game-cover-downloader-skill folder in the project root's corresponding location (e.g. .claude/skills/) and share it via Git.

Verify Installation

Restart your AI coding assistant after installation. Mention downloading game covers in a conversation to trigger the Skill. For example:

• "Download covers for N64 games"
• "Download NES covers and logos in Pegasus format"
• "What download presets are available?"

Project Structure

game-cover-downloader-skill/
  SKILL.md                       # AI Skill definition
  requirements.txt               # Python dependencies
  fetch_data.py                  # Data download script
  README.md                      # This file
  scripts/
    __init__.py
    cover_cli.py                 # CLI entry point
    thumbnail_matcher.py         # Core matching engine
    presets.json                 # Built-in preset rules
    user_rules.json              # User custom rules (generated by save-preset)
  libretro_data/                 # (not in repo — downloaded via fetch_data.py)
    mediadata/                   # Per-system thumbnail index JSON
    metadata/                    # Per-system ROM metadata JSON
    merged_games.json            # Merged game name database
    platform-aliases.json        # Platform name alias mapping

Common Options

License

MIT