Skip to content
Back to search

re-skill

Claude Code skill for reverse engineering retro games — disassemble, annotate, extract assets, web port

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/vgrichina--re-skill/badge.svg)](/listings/vgrichina--re-skill)

HTML

<a href="/listings/vgrichina--re-skill"><img src="/api/listings/vgrichina--re-skill/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.

# Clone or copy into your Claude Code skills directory
mkdir -p ~/.claude/skills
cp -r re/ ~/.claude/skills/re/

# Or clone the repo and symlink
git clone https://github.com/USER/re-skill.git
ln -s "$(pwd)/re-skill" ~/.claude/skills/re

After install, `/re` will appear as an available skill in Claude Code.

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.

SKILL.md · Manifest · 195 lines

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

  1. ---
  2. name: re
  3. description: >
  4. Reverse engineering session: disassemble, annotate, extract assets, build emulator, port to web.
  5. Use when working on a binary RE project with REVERSE.md and tools/ directory.
  6. disable-model-invocation: false
  7. allowed-tools: Read, Edit, Write, Glob, Grep, Bash(python3 tools/*), Bash(git log*), Bash(git status*), Bash(git diff*), Bash(grep*), Bash(head*), Bash(ls*)
  8. argument-hint: "[binary-path] or empty to continue"
  9. ---
  10. ## Live context
  11. - Open tasks: !`grep -m 10 '\[ \]' REVERSE.md 2>/dev/null || true`
  12. - Dead ends: !`head -50 dead_ends.md 2>/dev/null || true`
  13. - Sessions: !`ls re_loop_sessions/ 2>/dev/null | tail -5 || true`
  14. ## Dispatch
  15. **$ARGUMENTS given -> bootstrap new project**
  16. - Read [phases.md](phases.md), [reverse_template.md](reverse_template.md), [dead_ends_template.md](dead_ends_template.md), [re_loop_template.sh](re_loop_template.sh)
  17. - Scaffold: REVERSE.md, labels.csv, dead_ends.md, tools/ dir, re_loop.sh (fill config block)
  18. - Identify binary header -> fill Ph1 in REVERSE.md
  19. - Add first tasks to ## Next Tasks -> ### RE Investigation
  20. **no $ARGUMENTS -> continue from REVERSE.md**
  21. - Read CLAUDE.md for platform conventions, tool prefix, binary path
  22. - Pick top unchecked task from ## Next Tasks
  23. - Skim re_loop_sessions/*.txt (last 3) to avoid repeating work
  24. - Read dead_ends.md to avoid known dead-end approaches
  25. ## Task categories
  26. **RE investigation** (tools/dis.py, xref.py, search_bytes.py, decode_tables.py)
  27. 1. Run 2-3 tool calls
  28. 2. Write findings to REVERSE.md immediately — do NOT batch all investigation before writing
  29. 3. Add new addresses to labels.csv (addr,name,comment)
  30. 4. Repeat: more tool calls -> write, until task fully understood
  31. 5. Mark [x], add new [ ] discoveries
  32. **Web port fix** (web/ files)
  33. 1. Read the relevant web/ file first
  34. 2. Apply fix — values are already documented in REVERSE.md
  35. 3. Update REVERSE.md to note what changed
  36. 4. If new asset type decoded -> add section to web/catalog.html
  37. **Documentation** (docs/ directory)
  38. 1. docs/architecture_exe.md — binary layout, segment/bank boundaries, call graph with entry points + file offsets, module map, per-turn execution flow, data flow, shared data regions
  39. 2. docs/architecture_web.md — JS module graph with exports + dependencies, EXE->web mapping table, game loop flow, state machine with transitions
  40. Both files must exist before the project is considered complete.
  41. ## Knowledge base
  42. **labels.csv** accumulates across sessions. All disasm tools load it automatically.
  43. - Flat (DOS/unpacked): `offset,name,comment` — offset with 0x prefix e.g. `0x25DE9,main,entry point`
  44. - Banked ROM (NES/GB): `bank,addr,name,comment` — addr hex no prefix e.g. `0,C070,Reset,`
  45. - DS-relative (DOS): `DS:offset_hex,name,comment` e.g. `DS:0xCEAC,dt_physics,timestep`
  46. The comment column is optional but encouraged for non-obvious addresses.
  47. ## Stuck rule
  48. After 10 tool calls with no progress on a single task:
  49. 1. Append entry to dead_ends.md: tried / why-failed / better-approach / session number
  50. 2. Split stuck task into 2-3 smaller sub-tasks in REVERSE.md Next Tasks
  51. 3. Mark original [x] "Split into sub-tasks" — move on
  52. If the same task is attempted across 3+ sessions without progress, escalate: the task decomposition is wrong, rethink the approach entirely.
  53. ## Common gotchas (from past projects)
  54. - **MZ relocations break byte-pattern searches**: raw `search_bytes.py` misses far calls/jumps because segment values are patched at load time. Use `xref.py` which understands relocation tables.
  55. - **Decompress before disassembly**: compressed binaries are opaque. Always identify and unpack first (Ph2). All subsequent work uses the unpacked image.
  56. - **Two-level pointer tables**: flat decode shows pointer values, not the data they point to. Use `decode_tables.py --follow` to chase pointers to sub-tables.
  57. - **Tile index ≠ VRAM address**: many platforms use attribute/remapping tables between tile indices and actual video memory. Validate tile rendering against emulator, don't assume direct mapping.
  58. - **Don't search for composed text**: menu text, scores, and dialog are often built at runtime from format strings + data tables. Trace from code control flow, not string patterns.
  59. - **Bank-aware xref**: on banked ROMs (NES/GB), cross-bank byte matches are false positives. Always pass the bank filter to `xref.py`.
  60. - **WRAM tilemap stride varies**: Game Boy WRAM buffers may use 20-col stride, not the standard 32-col VRAM stride. Verify actual layout.
  61. - **Struct stride off-by-one**: a wrong stride corrupts every subsequent struct in the table. Cross-check decoded fields against emulator memory dump.
  62. ## Tool rules
  63. - Read not cat · Grep not grep · Glob not ls/find
  64. - Write a .py file first, then run it — never inline `python3 -c`
  65. - No third-party disassemblers (no radare2, Ghidra, ndisasm, mgbdis)
  66. - All tool scripts live in tools/ — invoke as `python3 tools/dis.py ...`
  67. ## Tool CLI reference
  68. All tools auto-load labels.csv for annotation. Prefix is `python3 tools/`.
  69. Core tools (signatures adapt per platform):
  70. ```
  71. dis.py <addr> [lines] # flat binary: file offset (hex)
  72. dis.py <bank> <addr> [nbytes] # banked ROM: bank + addr
  73. dis.py <file> <addr> [nbytes] --hunk N # Amiga hunk: target specific hunk
  74. xref.py <addr> # find all refs (calls, jumps, loads, stores)
  75. xref.py <addr> [bank] # banked: optional bank filter
  76. xref.py <addr> --code # scan known code segments only (faster)
  77. xref.py <addr> -r START END # restrict scan to file range
  78. xref.py <addr> -c N # show N bytes of context
  79. search_bytes.py <hex> [--context N] [--disasm [N]] # hex can be spaced or not
  80. decode_tables.py <addr> <count> <fmt> # fmt: u8/s8/u16/s16/u32/ptr16/farptr/q8/b8/nullstr
  81. decode_tables.py <addr> <count> struct:<n>:<f,f,...> # struct with field layout
  82. decode_tables.py <addr> <count> <fmt> --follow N FMT # two-level pointer tables
  83. extract_tiles.py # decode tiles/sprites to gfx/ PNGs
  84. render_screen.py # composite screen to gfx/screen_NNN.png
  85. ```
  86. Platform extras (built as needed):
  87. ```
  88. decompress.py # reverse-engineered decompressor (Ph2)
  89. seg_offset.py # convert between SEG:OFF and file/DS offsets (DOS)
  90. ds_lookup.py <exe> <addr> [-n N] [-s|-w|-d|-f32|-f64] # DS-relative memory viewer
  91. strings_dump.py [-g "pattern"] [-r START END] # string scanner with grep/range
  92. struct_dump.py # pre-configured struct dumper
  93. find_callers.py <addr> # find all callers (near+far), complements xref.py
  94. palette_dump.py [--accent] [--scan] # palette extractor
  95. a4resolve.py <file> [--dump | -- <offset>] # Amiga A4-relative library resolver
  96. hunk_scan.py / hunk_loader.py # Amiga hunk executable parser
  97. adf_extract.py / adf_debug.py # Amiga ADF disk image tools
  98. check_bank_refs.py # verify far references point to valid banks (NES/GB)
  99. extract_rom_banks.py # split MBC1/3 ROM banks (GB)
  100. render_sprites.py # render sprite sheets with palette/scale options
  101. render_level.py # full level/map renderer (Ph6)
  102. render_compare.py IMG1 IMG2 [--diff] # side-by-side pixel comparison
  103. compare_frames.py # pixel-diff emulator vs web port (Ph6)
  104. ```
  105. Scriptable emulator (Ph5.5, `python3 -m tools.emu` or `python3 tools/emu`):
  106. ```
  107. --dump-regs # load binary, print initial state
  108. --boot-test # run until first OS call or N instructions
  109. --run-func LABEL # jump to labeled function with pre-set state
  110. --break ADDR # breakpoint, dump registers + stack
  111. --trace # print each instruction
  112. --keys STEP:SCANCODE:ASCII # inject key input at step N
  113. --dump-screen FILE.png # screen capture
  114. --compare # export CSV for diffing against web port
  115. ```
  116. ## Scaffolded project structure
  117. ```
  118. REVERSE.md # data-range map, findings, task list, verification checklist
  119. labels.csv # addr,name,comment — grows across sessions
  120. dead_ends.md # stuck log — avoids repeating failed approaches
  121. re_loop.sh # autonomous session driver
  122. re_loop_sessions/ # session logs
  123. tools/
  124. instruction_set.py # CPU opcode database (built per platform)
  125. dis.py # targeted disassembler (auto-loads labels.csv)
  126. search_bytes.py # byte pattern search
  127. xref.py # cross-reference finder
  128. decode_tables.py # struct/table decoder
  129. extract_tiles.py # graphics decoder
  130. render_screen.py # screen compositor
  131. emu/ # scriptable emulator (Ph5.5, optional)
  132. gfx/ # extracted graphics
  133. web/
  134. index.html # game reimplementation
  135. catalog.html # asset browser for visual validation
  136. docs/
  137. architecture_exe.md # binary layout, call graph, data flow
  138. architecture_web.md # JS modules, EXE-to-web mapping
  139. ```
  140. ## Platform conventions
  141. Address notation and labels.csv format vary by platform. Set in CLAUDE.md during bootstrap.
  142. - **DOS flat/MZ**: file offsets `0xXXXXX`, DS-relative `DS:0xXXXX`, segment:offset `SEG:OFF`. Tools: seg_offset.py, ds_lookup.py. FPU emulation (INT 34h-3Dh) if Borland.
  143. - **NES/GB banked ROM**: `bank,addr` (addr hex no prefix). WRAM/HRAM labels use `bank='*'`. Tools: check_bank_refs.py, extract_rom_banks.py.
  144. - **Amiga hunk**: hunk-relative offsets, A4-relative library calls. Tools: hunk_scan.py, a4resolve.py, adf_extract.py.
  145. ## re_loop.sh (scaffolded for user, not agent-invoked)
  146. Scaffolded into the project from [re_loop_template.sh](re_loop_template.sh) during bootstrap. The user runs it from the terminal to drive autonomous sessions — the agent never invokes it directly.
  147. The ALLOWED_TOOLS in re_loop.sh should include wildcard patterns for on-the-fly scripts: `Bash(python3 tools/analyze_*)`, `Bash(python3 tools/audit_*)`, `Bash(python3 tools/check_*)`, `Bash(python3 tools/gen_*)`, `Bash(python3 tools/dump_*)`.
  148. ## Verification checkpoints
  149. Mark these in REVERSE.md as validation happens:
  150. - [ ] Ph3: 3+ functions traced and cross-checked against emulator trace
  151. - [ ] Ph4: 5+ sprites/tiles extracted and visually compared to emulator
  152. - [ ] Ph5: key data struct confirmed in emulator memory dump, all fields match
  153. - [ ] Ph6: full game session played, no major logic gaps found
  154. - [ ] Ph7: web port pixel-compared against emulator screenshots
  155. ## End of session
  156. - Mark completed task [x]
  157. - Add newly discovered unknowns as [ ] in the appropriate ### sub-section
  158. - Last line: `SESSION_SUMMARY: <one line>`
  159. See [phases.md](phases.md) when bootstrapping a new project.
README.md · README · 114 lines

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

  1. # /re — Reverse Engineering Skill for Claude Code
  2. A Claude Code skill that bootstraps and drives retro game reverse-engineering projects. Point it at a ROM or binary, and it scaffolds a full RE workspace — then iteratively disassembles, annotates, extracts assets, and ports the game to a web canvas, all from the CLI.
  3. ## What it does
  4. - **`/re path/to/rom.nes`** — Bootstrap a new RE project: identify the binary, scaffold REVERSE.md + labels.csv + tools/, create first investigation tasks
  5. - **`/re`** (no args) — Continue from where you left off: pick the next unchecked task from REVERSE.md and work it
  6. - **`re_loop.sh`** — Run autonomous sessions in a loop until all tasks are done, auto-committing after each
  7. ## Supported platforms
  8. The skill is platform-agnostic. It has been used on:
  9. - NES (6502, iNES format, 2bpp CHR tiles)
  10. - Game Boy (SM83/LR35902, Nintendo logo header)
  11. - DOS MZ (8086/Borland, EGA planar graphics)
  12. Adding a new platform means writing the `tools/instruction_set.py` for that CPU — everything else adapts.
  13. ## Install
  14. ```bash
  15. # Clone or copy into your Claude Code skills directory
  16. mkdir -p ~/.claude/skills
  17. cp -r re/ ~/.claude/skills/re/
  18. # Or clone the repo and symlink
  19. git clone https://github.com/USER/re-skill.git
  20. ln -s "$(pwd)/re-skill" ~/.claude/skills/re
  21. ```
  22. After install, `/re` will appear as an available skill in Claude Code.
  23. ## Prerequisites
  24. - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` command)
  25. - Python 3.8+
  26. - `pypng` (`pip install pypng`) — for tile/screen PNG export
  27. - `jq` — for re_loop.sh stream parsing
  28. ## What gets scaffolded
  29. ```
  30. your-project/
  31. REVERSE.md # Data-range map, findings, task list, verification checklist
  32. labels.csv # addr,name,comment — grows as you annotate
  33. dead_ends.md # Stuck log — avoids repeating failed approaches
  34. re_loop.sh # Autonomous session driver
  35. re_loop_sessions/ # Session logs
  36. tools/
  37. instruction_set.py # CPU opcode database (you build per platform)
  38. dis.py # Targeted disassembler (auto-loads labels.csv)
  39. search_bytes.py # Byte pattern search
  40. xref.py # Cross-reference finder
  41. decode_tables.py # Struct/table decoder
  42. extract_tiles.py # Graphics decoder
  43. render_screen.py # Screen compositor
  44. emu/ # Scriptable emulator (Ph5.5, optional)
  45. gfx/ # Extracted graphics
  46. web/
  47. index.html # Game reimplementation
  48. catalog.html # Asset browser for visual validation
  49. docs/
  50. architecture_exe.md # Binary layout, call graph, data flow
  51. architecture_web.md # JS modules, EXE-to-web mapping
  52. ```
  53. ## The phases
  54. 1. **Identify** — file header, platform, CPU, memory map
  55. 2. **Decompress** — unpack if compressed (skip if flat ROM)
  56. 3. **Disassemble** — build instruction_set.py + dis.py, start annotating
  57. 4. **Extract assets** — tiles, palettes, tilemaps to PNG; build catalog.html
  58. 5. **Map data structures** — tables, structs, pointer arrays
  59. 5.5. **Scriptable emulator** — (optional) minimal CPU emulator for automated data extraction and cross-validation when static RE isn't enough
  60. 6. **Validate** — cross-check everything against a running emulator
  61. 7. **Web port** — faithful reimplementation as plain HTML canvas
  62. ## re_loop.sh — autonomous mode
  63. ```bash
  64. ./re_loop.sh # default: up to 50 sessions
  65. ./re_loop.sh --max 10 # limit to 10 sessions
  66. ./re_loop.sh --tasks 3 # work 3 tasks per session
  67. ./re_loop.sh --max-turns 50 # limit Claude turns per session
  68. ./re_loop.sh --dry-run # print the prompt, don't run
  69. ```
  70. Each session: read REVERSE.md, pick top task, investigate with tools, update docs, commit. Stops when no tasks remain or `--max` is hit.
  71. ## Design principles
  72. - **No third-party disassemblers** — all tooling built from scratch for full understanding
  73. - **Write findings immediately** — every 2-3 tool calls, update REVERSE.md and labels.csv
  74. - **Dead-end tracking** — after 10 fruitless tool calls, log it and split the task
  75. - **Knowledge base accumulation** — labels.csv is loaded by all tools automatically; findings compound across sessions
  76. - **Verification checkpoints** — each phase has a cross-check gate before proceeding
  77. - **Visual validation** — catalog.html lets you compare extracted assets against the emulator
  78. - **Plain HTML/JS** — web port uses no build tools, served with `python3 -m http.server`
  79. ## Skill files
  80. | File | Purpose |
  81. |------|---------|
  82. | `SKILL.md` | Entry point — frontmatter, dispatch logic, session rules |
  83. | `phases.md` | Phase checklist with verification checkpoints |
  84. | `reverse_template.md` | REVERSE.md scaffold with memory map, data structures, state machine sections |
  85. | `dead_ends_template.md` | Dead-ends log template with lifecycle rules |
  86. | `re_loop_template.sh` | Autonomous loop script template |
  87. ## License
  88. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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