菜单
Drive the gbf-debug agent CLI to inspect, step, and script Game Boy ROM execution. Use when working with .gbsess files, gbf-debug, the gb JS object, breakpoints, watchpoints, symbols, or Game Boy ROM debugging in this workspace.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Use when implementing, reviewing, or closing gbllm QAT beads; enforces artifact-contract, differentiable Burn path, proof-test, acceptance-criterion movement, claim-to-gate, and no-future-variant checks.
Use when implementing, reviewing, or closing gbllm structured logging beads, including tracing event schemas, training/export/preflight logs, subscriber capture tests, and logging adoption claims.
Use when implementing, reviewing, or closing gbllm model topology or scalar gbf-model semantics beads, especially config validation, topology choices, parameter sharing, and non-Burn model behavior.
Use when implementing, reviewing, or closing gbllm ASM/ISA beads in gbf-asm, including instruction modeling, sections, symbols, builders, layout, relaxation, effects, privileges, encoders, cycle models, and listings.
Use when implementing, reviewing, or closing gbllm fixture beads, especially tiny model/artifact/workload fixtures, deterministic helper data, and artifact assertion helpers.
Use when implementing, reviewing, or closing gbllm sequence-state beads, including LinearState, BoundedKv, SequenceBlock traits, exported sequence facts, byte-backed state, and recurrent state tests.
| name | gbf-debug-usage |
| description | Drive the gbf-debug agent CLI to inspect, step, and script Game Boy ROM execution. Use when working with .gbsess files, gbf-debug, the gb JS object, breakpoints, watchpoints, symbols, or Game Boy ROM debugging in this workspace. |
| license | Proprietary. LICENSE.txt has complete terms |
| compatibility | Requires the gbf-debug binary built from this workspace |
| metadata | {"feature":"F-A8","bead":"bd-1aaz"} |
Use this skill when you need to debug a Game Boy ROM through the workspace's agent-facing CLI. The normal loop is: create a session with init, write a small JavaScript script, run it with exec, read the JSON envelope, then repeat with the new .gbsess.
gbf-debug init --rom target/rom.gb --sym target/rom.sym --out s0.gbsess
gbf-debug exec --in s0.gbsess --script run.js --out s1.gbsess
gbf-debug inspect s1.gbsess
Each command emits exactly one JSON object. Success writes to stdout; failure writes an ErrorEnvelope to stderr. Do not scrape prose output.
For a smoke test in this workspace, use gbf-emu/tests/fixtures/tiny_rom.gb with docs/review/f-a1/artifacts/tiny_rom.sym.
globalThis.result = ...; a lexical let result = ... is not captured.gb.read / gb.write for side-effect-free debugger access and gb.bus_read / gb.bus_write when you intentionally want CPU-bus side effects.gb.snapshot() / gb.restore(handle) for in-script branching. Copy the .gbsess file for cross-invocation forks.run_until* has a deterministic M-cycle cap. Pass an explicit cap when a script may run long.const entry = gb.symbol("gbf_runtime_dtiny_dentry");
gb.run_until(entry, 100000);
log("at-entry", { regs: gb.regs });
globalThis.result = { pc: gb.regs.pc, a: gb.regs.a };
gb.symbol(name) returns an address or null, but raises on banked ambiguity. Use gb.symbol_in_bank(name, bank) or gb.symbol_at_in_bank(addr, bank) when a name or address appears in more than one bank.
Date.now() is virtual emulator time, Math.random() is fixed-seeded, and console is unavailable. Use log(message, data) for structured logs; log timestamps use the same virtual clock as Date.now().
references/ENVELOPE.md has the JSON envelope shapes.references/GB_OBJECT.md lists the gb.* methods.references/PREDICATES.md explains closure vs string predicates.references/DETERMINISM.md covers virtual time, budgets, and watchdog behavior.assets/recipes/ contains reusable JavaScript snippets.