From prompt-to-romhack
Use when creating or editing Pokemon Red, Blue, or Yellow romhacks from pret disassembly repos, including cloning a clean workspace, installing agent helper tooling, vendoring RGBDS, building ROMs, running headless smoke checks, and opening the browser preview.
How this skill is triggered — by the user, by Claude, or both
Slash command
/prompt-to-romhack:prompt-to-romhackThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this plugin when a user asks for a playable Pokemon Red, Blue, or Yellow romhack, dialogue/data/map edits, build verification, emulator smoke testing, or a browser preview.
Use this plugin when a user asks for a playable Pokemon Red, Blue, or Yellow romhack, dialogue/data/map edits, build verification, emulator smoke testing, or a browser preview.
Do not assume the pokered or pokeyellow disassembly is already present. Start by cloning the requested base repo or fork into the workspace, then install this plugin's helper tooling into that clone.
From the plugin root:
node scripts/prompt-to-romhack.mjs setup --game red --dir ./pokered
node scripts/prompt-to-romhack.mjs setup --game yellow --dir ./pokeyellow
For a fork or branch:
node scripts/prompt-to-romhack.mjs setup --game red --repo https://github.com/owner/pokered.git --branch my-branch --dir ./my-hack
Defaults:
red and blue clone https://github.com/pret/pokered.git.yellow clones https://github.com/pret/pokeyellow.git..prompt-to-romhack/config.json inside the cloned workspace.If the repo already exists, install or refresh only the helper layer:
node /path/to/prompt-to-romhack/scripts/prompt-to-romhack.mjs install-tools --workspace .
node /path/to/prompt-to-romhack/scripts/prompt-to-romhack.mjs vendor-rgbds --workspace .
Inside the cloned disassembly workspace, run:
node scripts/prompt_to_romhack.mjs doctor
If tools are present, use the helper instead of calling the emulator manually:
node scripts/prompt_to_romhack.mjs preview --rom red --allow-missing-logo
node scripts/prompt_to_romhack.mjs preview --rom yellow --allow-missing-logo
Use --allow-missing-logo only for a first mechanical check. For a real hack
preview, generate or choose a distinctive non-official title logo under
web/romhack-preview/assets/ and pass it with --logo.
For early runtime confidence without opening the browser:
node scripts/prompt_to_romhack.mjs smoke --rom red --path early-game
node scripts/prompt_to_romhack.mjs headless --rom red --path pallet-town
node scripts/prompt_to_romhack.mjs headless --rom yellow --path boot
Red/Blue currently have the strongest smoke-path coverage. For Yellow, begin with boot, main-menu, build, and browser preview unless you have validated a longer path in that checkout.
rg..gbc, .map, .sym, .o, .1bpp, .2bpp, and .pic outputs.node scripts/prompt_to_romhack.mjs build --rom red, --rom blue, or --rom yellow.roms.sha1. For real hacks, expect the SHA-1 to differ.node scripts/prompt_to_romhack.mjs smoke --rom red --path early-game --no-build --expect-map REDS_HOUSE_2F --expect-coord 3,7.node scripts/prompt_to_romhack.mjs headless --rom red --path pallet-town --no-build --expect-map PALLET_TOWN --expect-coord 5,6.web/romhack-preview/assets/. Avoid official logo lettering, ball emblems, character art, or mascots.node scripts/prompt_to_romhack.mjs preview --rom red --no-build --title "Hack Title" --logo /web/romhack-preview/assets/hack-title-logo.png --romhack-id hack-title. The helper fails before serving the webpage when no preview logo is present; use --allow-missing-logo only for mechanical tests where visual review is not needed.Keep --romhack-id stable for a single playthrough so SRAM persists across rebuilds and page reloads.
While the preview is open, use the local rendezvous API through:
node scripts/prompt_to_romhack.mjs live session
node scripts/prompt_to_romhack.mjs live status
node scripts/prompt_to_romhack.mjs live read wCurMap,wXCoord,wYCoord
node scripts/prompt_to_romhack.mjs live write wEnemyMonHP=0,1
node scripts/prompt_to_romhack.mjs live press a --frames 8
node scripts/prompt_to_romhack.mjs live screenshot --out artifacts/live/preview.png
node scripts/prompt_to_romhack.mjs live refresh-map
node scripts/prompt_to_romhack.mjs live apply-rom-diff
Before any godmode/state edit, read the live RAM state instead of relying on the last screenshot or previous route. At minimum check live status and live read wCurMap,wXCoord,wYCoord,wIsInBattle.
After setup, the cloned workspace receives:
docs/prompt-to-romhack.md for the high-level prompt-to-ROM loop.docs/romhack/edit-surfaces.md for where common data lives.docs/romhack/game-logic.md for battle and formula work.docs/romhack/scripts-and-dialogue.md for scripts, text, and cutscenes.docs/romhack/headless-emulator-testing.md for smoke-test design.docs/romhack/live-patching.md for live preview and ROM-diff iteration.docs/romhack/emulator-only-limits.md for emulator-targeted hack boundaries.Use the docs as orientation, then verify against the actual checkout because forks can drift.
For every prompted hack, at minimum report whether the ROM builds. When the change affects early gameplay, run a relevant headless smoke path before browser review. When browser testing is requested or visual/human review matters, use the preview URL and verify the title screen/new game path or the changed area. Keep notes about behavior that was not play-tested.
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub psm14/prompt-to-romhack --plugin prompt-to-romhack