How to use the Game Automation agent skill for mod testing

What the game-automation skill lets the agent do

The skill is built around a loop: launch the game, navigate to the scene you need, set it up, act, take a screenshot and read the logs, then decide what to change. The source describes it as the agent's hands and eyes, and says the real game is the oracle for whether a mod works.

Its main tooling is the universal-modder command line tool (um), used through um win on Windows, including from WSL. Other platforms get notes rather than a full toolset.

• Launch a game through Steam or its exe, with optional launch flags
• Put the game in windowed mode at a fixed client size
• Take screenshots of the game window, including GPU-rendered games
• Send mouse clicks, drags, key presses, held keys and relative mouse movement
• Read and clean up crashed processes, and kill a process by exact PID
• Add an in-game JSON bridge so the agent can read menus and act without looking at pixels

Install the game-automation skill

Download the ZIP from this page and unzip it. The skill is a single file, SKILL.md. Put the unzipped folder in one of two places: ~/.claude/skills/ to make it available everywhere, or a project's .claude/skills/ folder to limit it to that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

The skill runs scripts and needs local tools before it is useful. On Windows, run um win setup once. The source says this installs PowerShell tools and an ffmpeg build with gfxcapture support, and picks an encoder such as NVENC, AMF, QSV or x264.

Check what you need before you start

The main tooling expects Windows, native or through WSL, with PowerShell available. The game must be installed locally, optionally through Steam. You also need the universal-modder CLI (um). Python is needed only for longer scripts that use the um.win module.

The skill does run scripts. It does not use the network, according to the source.

• Windows (native or WSL) with PowerShell
• ffmpeg with gfxcapture, set up by um win setup
• Python, for longer scripts using the um.win module
• The game installed locally, optionally via Steam
• The universal-modder CLI (um)

Use the basic commands

These commands cover the common path: list windowed processes, launch the game, take a screenshot, and send input. Coordinates for clicks are in the game window's client area. Note that each um win drive call starts PowerShell, which takes one to two seconds, so put timed key combinations into a single call.

To drive the game from Python instead, the source shows from um.win import Drive, shot, Recorder, then creating a Drive object for the process and calling focus, click and key.

• Use um win ps to list windowed processes with pid, name and title
• Use --scale 0.33 on screenshots to get a cheap copy to look at; multiply click coordinates by 3 to map back
• Use sleep <ms> inside a drive call to pause between steps
• Use idle to see how many seconds since the user last touched the mouse or keyboard; it does not wait

Trigger the skill with a natural request

You do not need to type commands yourself. Ask in plain language for the kind of job you want, and the agent will pick this skill when the request matches its description. The description says to use it when a mod must be verified in game, when menus need navigating automatically, or when a repeatable test or demo scene is needed.

Name the game and say what to check. The more specific you are about the menu, the change, and what success looks like, the easier it is for the agent to plan the run.

• "Launch Terraria through Steam, load my test world and screenshot the inventory after my recipe change."
• "Verify my mod in the game: start it, open the settings menu and tell me whether the new option appears."
• "Build a repeatable test scene that spawns three waves of enemies and records the result."
• "The game crashed and Steam says it is already running. Find the leftover crash reporter and clear it."

Keep windows and menus predictable

Games often hide window settings. The source lists several ways to set windowed mode at a fixed size: an ini file such as GameUserSettings.ini for Unreal Engine, registry values for Unity games, launch flags such as -windowed -w 1920 -h 1080, or the game's own registry keys. um win drive with size 1920 1080 also resizes most windowed games.

Skipping intros and jumping straight to a test state saves a lot of time. The source suggests launch flags such as -skipintro or -nosplash, loader flags such as tModLoader's -skipselect, and a save made for testing. For a copy of a game only, you can remove intro videos.

• Stop games from pausing when unfocused, where the engine allows it (for example Unity's Application.runInBackground = true)
• Record the menu click points once in MODLOG.md so later runs do not need repeated screenshots
• Prefer a chat or console command in your mod for setup, such as giving items or teleporting, because it turns a multi-click test into one line

Use an in-game bridge instead of pixels

For repeatable tests, the skill can add a JSON-lines socket inside your mod on 127.0.0.1. The source points to examples/terraria-tmodloader/reference/AgentBridge.cs as a reference. Commands include observe, which returns menu options or world state as text, click with an id, controls, and step.

The source says to handle each request on the game's main thread after an update so replies are consistent, and to read menus from the UI tree while leaving out destructive buttons such as delete. With a bridge the agent can play without screenshots at all.

Handle crashes and leftover processes

Crash reporters such as BugSplat BsSndRpt64.exe, CrashReportClient.exe and UnityCrashHandler64.exe can keep running and make Steam report that the game is already open. Use um win ps to find them and um win kill <pid> to stop the exact process.

Do not use pkill -f or wildcard taskkill /IM, because the pattern can match the agent's own shell or other apps. After a crash, read the loader or game log first, then the Windows Event Viewer Application log for native crashes.

Follow the safety rules

Input goes only to the game, and the skill refuses to send input while another app is in the foreground. Even so, the source is clear that driving a real PC needs a human check. The GTA V example in the skill shows how keystrokes from a person at the keyboard can reach an online mode and trigger a server warning.

Do not focus a game with an online mode while someone is typing. Check idle, ask the person to click, keep sessions short, and launch with anti-cheat off so online mode cannot start. Unattended runs are fine only once the user says so. Screenshots also cost tokens, so use the reduced-scale copies.

• Avoid online-enabled games while someone uses the PC
• Do not run unattended on a shared machine without checking who is at the keyboard
• If idle is under a minute, ask before driving the game
• Turn Windows Auto HDR off for the game while capturing, because it washes out screenshots

Linux and macOS notes

The skill's main tooling is for Windows. For Linux on X11 the source lists xdotool for window focus, mouse and key input, and import or ffmpeg x11grab for screenshots. Wayland setups use ydotool and grim. Proton games are Windows games under Wine, so launch options such as WINEDLLOVERRIDES and PROTON_LOG=1 go in Steam.

On macOS the source mentions screencapture with a window id, and osascript or cliclick for input. The terminal needs Accessibility and Screen Recording permission.