Skip to content
Back to search

Game-Decompilation-Skill-For-Claude

Skill for creating a bytematching decompilation of a game with Claude

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lemiur--game-decompilation-skill-for-claude/badge.svg)](/listings/lemiur--game-decompilation-skill-for-claude)

HTML

<a href="/listings/lemiur--game-decompilation-skill-for-claude"><img src="/api/listings/lemiur--game-decompilation-skill-for-claude/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Copy the `.claude/skills/` directory into your decompilation repository (project skills), or into `~/.claude/skills/` to make them available in every project:

cp -r .claude/skills/* /path/to/your-decomp/.claude/skills/

Claude Code finds the skills automatically. Claude picks them up from the task ("why won't this function match?"), or you can invoke one directly, for example `/matcher` or `/wall-identifier`.

The project's `AGENTS.md` always overrides the skills' defaults.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 155 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Game Decompilation Skill For Claude
  2. A set of [Claude Code](https://claude.com/claude-code) skills for building a **byte-matching decompilation** of a game.
  3. The skills are project-independent. They describe the method (how to reconstruct, diagnose, permute, review and
  4. merge), and each game repository supplies its own commands and conventions through an `AGENTS.md` file.
  5. ## Explanation
  6. Think of a retro video game as a finished dish—say, a complex chocolate lava cake.
  7. When developers originally made the game, they wrote human-readable source code (the recipe) and ran it through a compiler (the baking process), turning it into raw machine instructions that only hardware like an N64 or PlayStation can execute (the baked cake).
  8. ### Decompilation: Reverse-Engineering the Recipe
  9. **Decompilation** is the process of taking that finished cake, analyzing every bite in a laboratory, and writing down an exact, readable recipe from scratch.
  10. Programmers use disassembly tools like Ghidra to read the raw machine numbers, determine the original logic, and rewrite it into clean, readable code (usually C or C++).
  11. - **The Goal:** Match the original logic so closely that if you run the reconstructed recipe through the original compiler, it produces the exact same binary game file byte-for-byte (known as a "matching decompilation").
  12. - **Famous Examples:** *Super Mario 64*, *The Legend of Zelda: Ocarina of Time*, *The Legend of Zelda: Twilight Princess*
  13. ### Static Recompilation: Translating the Cake Piece by Piece
  14. **Static recompilation** takes a shortcut. Instead of figuring out *what the recipe meant* in human terms, automated software translates the old machine instructions directly into new machine instructions for a modern PC.
  15. - It doesn't yield clean, readable source code with variables named `player_health` or `spawn_enemy()`.
  16. - Instead, it generates a massive wall of low-level instructions that essentially says: *"Where the N64 chip modified register $a0, modify this modern x86 variable."*
  17. - **The Goal:** Speed and compatibility. It gets the game running natively on modern hardware without the performance overhead of a traditional emulator
  18. ### How They Compare
  19. | **Feature** | **Decompilation** | **Static Recompilation** |
  20. | ------------------------ | --------------------------------------------- | ------------------------------------------------ |
  21. | **Output** | Human-readable source code (a real recipe) | Translated machine logic (automated translation) |
  22. | **Moddability** | Total freedom (add new levels, physics, AI) | Limited (hard to modify code you can't read) |
  23. | **Platform Portability** | Compiles to anything: PC, Switch, Mac, phones | Ties closely to the recompiler toolchain |
  24. ### Why You Should Consider Decompiling Over Recompiling
  25. While static recompilation gets a game up and running natively quicker, full decompilation remains the gold standard for long-term preservation and deep modification:
  26. 1. **True Modernization (Beyond Resolution):**
  27. A recompiled game often pull off 4K and 60fps, but performance is not as good as it would be coming from a proper decompilation, and many modernizations often remain difficult or impossible.
  28. 2. **Deeper, Bug-Free Modding:**
  29. In a recompiled game, tweaking gameplay requires patching raw assembly or memory offsets—easy to crash. In a decompiled project, a modder can open `player.c`, change a line like `jump_force = 12.0f;`, add entirely new items, rewrite boss AI, or stitch together custom levels with seamless new mechanics.
  30. 3. **Total Portability Across Architectures:**
  31. Once clean C code exists, it can be compiled for virtually any platform that has a C compiler. You can run the game on Windows, macOS, Linux, Android, a modern handheld like the Steam Deck, a jailbroken Nintendo Switch, or even a microcontroller or smart refrigerator.
  32. 4. **Preserving Development History:**
  33. Decompilations often reveal unused levels, discarded assets, forgotten developer comments, and insights into how legendary studios solved impossible hardware constraints 25 years ago. It transforms a locked black box back into living software history.
  34. 5. **Community Contribution**
  35. Successfully decompiling one game will dramatically improve the ease and speed with which related (even very loosely, sometimes!) games can be decompiled.
  36. ### When You <u>Should</u> Recompile
  37. Decompilation takes more time/usage than recompilation by its nature. The more code in the game, the longer decompilation is going to take.
  38. My experience has been that PS1 and PS2 generation games are pretty doable. Usage is quite high: you're not going to be able to do multiple games per week, that's for sure, but these are manageable projects, especially if you can get other people to collaborate with you. My experiments with Wii game lead me to think they likely fit into this category as well
  39. Anything PS3/360 generation or higher will be a <u>long</u> .process. This toolset will help with those projects if you choose to pursue them, but unfortunately they can't change the fact that there's almost definitely an enormous amount of code involved. These projects will take months, even with LLM assistance.
  40. ## How to Use
  41. Install this Claude skill (ask Claude to do it for you if you need help)
  42. In an empty folder, write a README.md document pointing Claude to your game files/game folder (or just put your game files in the folder itself). If you already have your compiler, put this in the folder as well. In a new Claude session, run `/orchestrator` and answer the following questions.
  43. Make sure to ask for code quality passes intermittently to ensure good quality code.
  44. If you want a PC port after reaching 100% bytematch, you can run `/native-platform-porting`. Add any additional features you want, like mouselook or high framerates after `/native-platform-porting` in your message.
  45. It's that easy!
  46. This will work well on games for the PSX/N64 era on. Your mileage will vary on older systems.
  47. ## A Couple Personal Asks
  48. - **Don't steal other people's projects**
  49. - If you want to contribute to someone else's project, please ask. If they don't want AI contributions, then please don't take their code and use it as a basis to throw together a decompilation quickly. That's a bad look for all of us in the scene.
  50. - **Try to Learn Something**
  51. - It's very easy to just ask Claude to do the thing and watch the progress bar go up. If you don't know how to program, I'd absolutely recommend learning. I've yet to encounter anyone who's regretted learning to program (although plenty who have regretted going into SWE professionally!). For decompilation related learning resources specifically, https://decomp-academy.dev seems really nice.
  52. - **Open Source Your Project**
  53. - We wouldn't need to decompile anything if everything was open source from the start. Don't contribute to the endless pile of closed source code. Put what you have on GitHub so others can benefit from it.
  54. ## The skills
  55. | skill | use it to |
  56. |---|---|
  57. | [`matcher`](.claude/skills/matcher/SKILL.md) | reconstruct and byte-match functions, units, classes, globals and referents; recover lost matches; finish a match to the code rules |
  58. | [`wall-identifier`](.claude/skills/wall-identifier/SKILL.md) | classify a stuck function as an inline/call-set, control-flow, register/schedule or masked/referent wall, and route it to the right lever |
  59. | [`helper-recovery`](.claude/skills/helper-recovery/SKILL.md) | find inline helpers, accessors and macros the compiler expanded, restore them, and apply them at every site |
  60. | [`permute`](.claude/skills/permute/SKILL.md) | run bounded multi-island permuter searches, keep several distinct states, and turn what they reveal into honest source changes |
  61. | [`decomp-code-rules`](.claude/skills/decomp-code-rules/SKILL.md) | write, review or lint reconstructed source; judge fakematches against genuine period idioms; choose a naming and layout style |
  62. | [`orchestrator`](.claude/skills/orchestrator/SKILL.md) | run a campaign of parallel matcher workers in separate git worktrees, review their results, and merge them through a fixed procedure |
  63. Supporting references:
  64. - [`matcher/references/AGENTS-template.md`](.claude/skills/matcher/references/AGENTS-template.md): the
  65. project-guide template, including the project adapter, scores, workflow and byte gate.
  66. - [`matcher/references/levers.md`](.claude/skills/matcher/references/levers.md): source-shape levers for
  67. steering codegen honestly.
  68. - [`decomp-code-rules/references/rules.md`](.claude/skills/decomp-code-rules/references/rules.md): the full rule
  69. catalogue (R1 and up) with examples, tiers and the fakematch table.
  70. - [`decomp-code-rules/references/style-defaults.md`](.claude/skills/decomp-code-rules/references/style-defaults.md):
  71. default C and C++ naming and layout tables, taken from Quake III Arena and DOOM 3 BFG, for when the original's
  72. style is unknown.
  73. ## How they fit together
  74. ```
  75. orchestrator ── plans lanes, launches workers, merges
  76. │
  77. └─ matcher ── the working loop for each function
  78. ├─ wall-identifier ── "why won't this match?"
  79. ├─ helper-recovery ── open-coded helpers and macros
  80. ├─ permute ────────── proven register/schedule residue only
  81. └─ decomp-code-rules ─ what every line must satisfy, and what counts as a match
  82. ```
  83. ## Installation
  84. Copy the `.claude/skills/` directory into your decompilation repository (project skills), or into
  85. `~/.claude/skills/` to make them available in every project:
  86. ```bash
  87. cp -r .claude/skills/* /path/to/your-decomp/.claude/skills/
  88. ```
  89. Claude Code finds the skills automatically. Claude picks them up from the task ("why won't this function
  90. match?"), or you can invoke one directly, for example `/matcher` or `/wall-identifier`.
  91. The project's `AGENTS.md` always overrides the skills' defaults.
  92. ## Requirements
  93. The skills assume you already have a matching-decomp toolchain. They don't provide one. Typically that means:
  94. - the original compiler and linker (or an exact equivalent) and the retail binary;
  95. - a split/build setup that can compile individual units and compare them with retail;
  96. - a disassembler or diff tool, and optionally a decompiler, a permuter and objdiff;
  97. - git, since the orchestrator works in worktrees and merges through branches.
  98. ## Legal
  99. This repository contains only methodology. It contains no game code, assets or binaries. Use it with games you
  100. own, and follow the laws and the original developer's terms that apply to you.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.