How universal-modder turns a game install into a ten step agent loop

What the fixed ten step loop asks an agent to do

universal-modder does not leave an agent to invent a modding approach from scratch. It hands the agent a `mod-any-game` skill and a fixed sequence of ten steps that does not change between games: search the knowledge base, recon and pick a route, set up a safe lab with saves backed up, read the actual code, build one working slice, generate assets, verify in the real game, record, package, then write a field note for the next agent. Two details decide whether that sequence suits you. The deliverable at step 5 is a slice that runs, so a session either ends with something loadable in the game or stops before packaging. And the archive write is step 10 rather than step 1, so notes accumulate from finished work instead of from intentions. The stated users are AI coding agents, and the stated subject is a PC game you already own on disk, pointed at by path.

Five agent configs, five plugin manifests, two copies of the skills

Inside a clone, one set of instructions is reachable from several directions. `.agents/skills` serves Codex, Gemini CLI, Copilot, Cursor and OpenCode, `.claude/skills` serves Claude Code, and both are described as copies of `skills/`. MCP configuration is split the same way, across `.mcp.json`, `.codex/config.toml`, `.cursor/mcp.json`, `.vscode/mcp.json` and `opencode.json`, while `AGENTS.md` holds the instructions that `CLAUDE.md` and `GEMINI.md` point to. One detail outranks the list length: `opencode.json` points OpenCode at `skills/` directly, and the two skill directories are copies, so an edit to `skills/mod-any-game` reaches OpenCode in a clone at once and reaches the other five agents only when the copies are refreshed. Plugin descriptors multiply the same maintenance question. The top level holds `.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, `gemini-extension.json` and `plugin.json`, plus a second `mcp.json` with no leading dot that no install step names. `hooks/`, `bin/` and `tests/` sit in the tree too, with no explanation anywhere in the install section.

Installing per agent and putting the um CLI on PATH

Begin with the two agents that install from a marketplace identifier, because a plugin install also puts the um CLI on PATH:

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder
codex plugin marketplace add rehan-remade/universal-modder
codex plugin add universal-modder@universal-modder
gemini extensions install https://github.com/rehan-remade/universal-modder
npx skills add https://github.com/rehan-remade/universal-modder

Take the line that matches your agent. Copilot needs `chat.plugins.enabled` switched on plus the Chat: Install Plugin From Source command, and Cursor and OpenCode expect a clone that you open the agent inside. The skills-only row at the bottom is the fallback for any agent that reads the Agent Skills format, but that row never mentions the CLI, so treat the next step as mandatory rather than optional. Anywhere else:

uv tool install git+https://github.com/rehan-remade/universal-modder     # or: pipx install git+...
export FAL_KEY=...

That key feeds both the fal MCP server and `um fal`. Git, Python 3.10+ and ffmpeg are the prerequisites outside Python, uv is the recommended installer, and Blender is needed for 3D to sprite renders. Windows games are driven natively or from WSL, so step 7 of the loop runs in one of two environments depending on where the install lives.

Field notes record versions, routes and a symptom to cause fix chain

The knowledge base is the part of this project that outlives a single session. Notes live under `knowledge/` and each one gives the exact versions that worked, the route and why it was chosen, what the engine really does, how the result was verified, and gotchas written as symptom to cause to fix. The CLI wraps that workflow:

um kb search "grand theft auto"                 # before you start: prior art (works outside the repo too)
um kb new --game "Hades II" --title "A new boon god" --from-scan hades --agent "Codex (gpt-6)"
um kb check knowledge/games/hades-ii/a-new-boon-god.md
um kb pr knowledge/games/hades-ii/a-new-boon-god.md --yes    # after your human says OK: branch, push, PR

Two things stand out. The search example is marked as working outside the repo, while the other three commands are written as paths inside `knowledge/games/`, so a note started outside a clone has to be brought in before `um kb pr` can branch and push. The last line also carries its own condition, a human saying OK first, which puts a person between step 10 of the loop and the archive. `knowledge/INDEX.md` is the index, and `CONTRIBUTING.md` holds the rules for humans and agents alike: no game files, no decompiled dumps, no cheating other players, and an honest status and verification.

Twelve playbooks against three shipped example directories

The `mod-any-game` skill bundles 12 engine playbooks, and that number is easier to misread than any other figure here. The list under it names far more than twelve engines: Unity, Unreal, .NET/XNA for Terraria, Stardew and Celeste, Godot, Source 1 and Source 2, Bethesda titles, Minecraft, AoE2 and Genie, one bucket holding RE Engine, FromSoft, GTA, Cyberpunk and BG3, native C++, another bucket grouping GameMaker, RPG Maker, Ren'Py, Paradox, Doom, HTML5, LÖVE and Java, and retro decomps. Twelve counts playbooks, not engines, so a game whose engine nobody has met yet can land inside an existing playbook rather than adding one. Depth ships separately: three example directories, `examples/aoe2-de-civ/`, `examples/minecraft-gta5-passthrough/` and `examples/terraria-tmodloader/`. A second skill named `game-recon` sits beside the first in the table and covers step 2 of the loop. Of the four community notes listed as samples, three use Minecraft as the host game, which tells you where the accumulated experience sits.

Asset generation needs a key, ffmpeg, Blender and three Python packages

Asset work carries the cost. A fal API key powers both the MCP server and `um fal`, and the only keyless path described is `um comfy`, which uses a local ComfyUI server for images. Nothing covers 3D or audio without a key, and Blender is called out separately for 3D to sprite renders. The declared Python surface is small:

[project]
name = "universal-modder"
version = "0.2.0"
requires-python = ">=3.10"

`pillow>=10`, `numpy>=1.24` and `pyyaml>=6` are the whole runtime list, the entry point is `um = "um.cli:main"`, and a hatchling build packages the um directory. ffmpeg, Git and Blender sit outside that list, and no install command checks for them. So a machine with Python in place but ffmpeg missing passes installation and fails later, at the moment a verified session is supposed to become a video. Verify those binaries before the first run rather than after.

Loader based modding against decompiling a game you lack source for

Two modding routes appear inside this repository, and the gap between them decides how much work the agent is really doing. The Terraria example sits in `examples/terraria-tmodloader/`, the loader route, and the playbooks cover .NET/XNA for Terraria, Stardew and Celeste, all games that ship a supported loader. The community notes take the other route: Halo 3 weapons, Covenant, vehicles and maps ported into Minecraft, and an Elden Ring conversion delivered as a native Rust DLL through ME3. A loader hands the agent a project layout, a target version and a reload path, which leaves step 5 as assembly work. The decompile route pushes the weight into step 4, reading the actual code, and the output is a binary the agent built. `CONTRIBUTING.md` then rules decompiled dumps out of the repository, so this route yields a mod and a note, never the vendor's files. Where a maintained loader exists, what you gain here is asset generation plus the archive. Where none exists, you are supervising a reverse engineering run and the ten step loop is mostly steps 4 and 7.

The loop has no undo step and its scope is single player

The loop has no undo. Step 3 sets up a safe lab with saves backed up, step 7 verifies in the real game, and the work is then recorded and packaged. Nothing documents how to revert a mod that loads badly, how a backed up save is restored, or what a run does when recon picks the wrong engine, so recovery falls to your own copies. Scope is narrow by design: the Elden Ring note is explicitly an offline conversion, the contribution rules ban cheating other players, and every prompt in the try-it section points at your own install rather than a live service. The published version is 0.2.0 under the MIT licence and the last push was on 2026-10-06, so upgrades arrive the way installs do, through the plugin marketplace or a fresh clone, with no upgrade note to read first. MIT covers the skills, the CLI and the notes as published here, while the games themselves stay outside the repository by rule.

Editorial conclusion

Adopt universal-modder when you own the game, run an agent that reads AGENTS.md, and accept that every published field note passes a human before the pull request. Leave it alone for online multiplayer or for a pipeline you need to replay with identical results, because the ten step loop is agent judgement rather than a script. Before the first mod, confirm FAL_KEY, ffmpeg and Blender are present, then run um kb search for the game, and check whether one of the 12 playbooks already covers its engine.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. rehan-remade/universal-modder on GitHub