Nes Rom Debug

What it does

When your agent uses it

• The user wants to disassemble a .nes ROM
• Inspect 6502 machine code
• Compare two NES ROMs side-by-side
• Debug transpiler output

Example prompts

• “the ROM looks wrong”
• “what did the transpiler emit”
• “/nes-rom-debug”

Requirements

• Python 3

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

1. 1File sizes
2. 2Total byte differences (header / PRG / CHR breakdown)
3. 3Contiguous diff groups with NES addresses
4. 4Side-by-side disassembly of the largest diff region with match/mismatch markers
5. 5Instruction mismatch count (ignoring absolute addresses, since the two compilers may place subroutines at different offsets)

What it can do on your machine

Read from SKILL.md and the folder at commit 42ca23d. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • python
  • dotnet

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Nes Rom Debug loads about 1.5k tokens when it runs. Until then it costs about 161 tokens; SKILL.md has 509 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~161

When it runs · the whole SKILL.md, loaded when a task matches

~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jonathanpeppers/dotnes at commit 42ca23d, republished under its MIT licence (© jonathanpeppers). 509 words, ~1,480 tokens.

name

nes-rom-debug

description

Disassemble and debug NES ROM files (.nes) produced by the dotnes transpiler. Use this skill whenever the user wants to disassemble a .nes ROM, inspect 6502 machine code, compare two NES ROMs side-by-side, debug transpiler output, investigate byte differences between a cc65 reference ROM and a dotnes ROM, or understand what 6502 instructions the transpiler emitted. Also use when the user mentions disasm, disassembly, PRG ROM, ROM bytes, NES addresses, or wants to look at the hex/binary output of a build. Even if the user just says something like "the ROM looks wrong" or "what did the transpiler emit", this skill applies.

python scripts/disasm.py <file.nes> [start_hex] [end_hex]

# Disassemble the entire PRG ROM
python scripts/disasm.py samples/hello/hello.nes

# Disassemble only the main() region
python scripts/disasm.py samples/hello/hello.nes 8500 8600

# Disassemble the interrupt vectors area
python scripts/disasm.py samples/hello/hello.nes FF00 FFFF

$8500: A9 02     LDA #$02
$8502: 20 61 85  JSR $8561
$8505: 85 17     STA $17
$8507: D0 F7     BNE $8500

python scripts/compare_rom.py <reference.nes> <dotnes.nes>

dotnet run scripts/ildump.cs -- <path-to-dll>

Offset    Size     Content
0x00      16       iNES header (starts with "NES\x1A")
0x10      32768    PRG ROM (mapped to NES $8000-$FFFF)
0x8010    8192     CHR ROM (pattern tables for tiles/sprites)

python scripts/compare_rom.py reference.nes output.nes
# If diff at $8600-$8620:
python scripts/disasm.py reference.nes 85F0 8630
python scripts/disasm.py output.nes 85F0 8630

# Look at the last few bytes for the vectors
python scripts/disasm.py myrom.nes FFF0 FFFF

# The RESET vector value tells you where startup is
# Then disassemble from there to find the JMP to main

# The test DLLs are in src/dotnes.tests/Data/
# Build the test project to get the .received.bin
python scripts/compare_rom.py path/to/verified.bin path/to/received.bin

© jonathanpeppers, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .github/skills/nes-rom-debug of jonathanpeppers/dotnes.

Open the folder on GitHubat commit 42ca23d