Skip to main content
skill CX Codex

console-levels — Claude Code skill: what it does, how to install

console-levels is a Claude Code skill that maps an extracted PS2 disc, unpacks the archives holding levels and repacks them after edits. It fires on requests like "unpack this archive".

MIT ★ 449 updated 2026-10-22

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Jakeschincariol/console-skill
/plugin install console-skill@console-skill
Open on GitHub

What console-levels does

The skill puts datascan.py in the agent's hands, with scan, unpack, repack, diff, strings and files subcommands. scan walks an extracted disc and reports file sizes, type by magic, entropy and any table of contents it guesses, with a confidence score. unpack splits CRI AFS archives and detected table-of-contents archives into a folder with an index.json; repack puts them back in archive order and alignment, holding offsets steady while edits fit their slots.

diff takes two files or folders and names the bytes a change touched. strings dumps text. files parses a port log for [sceCdSearchFile:ok] lines and lists what a level loads. Output lands under console/; the disc files themselves are left alone.

An archive at more than 7.5 bits per byte throughout stays packed until the game's own decompressor is located in the ELF. repack will not overwrite an existing file without --force. Only discs the user dumped personally go in, and what level bytes mean gets worked out by diffing two levels or reading the loader in Ghidra.

What it helps with

  • find which archive holds the levels
  • split DATA.BIN into editable entry files
  • repack an archive with offsets and alignment intact
  • see which bytes a level edit touched
  • list the disc files a stage loads, straight from the port log

Example prompts for the agent

  • Unpack console/disc/DATA/STAGE.AFS into console/levels/STAGE
  • Diff 0003_ST01.DAT against 0004_ST02.DAT as f32 and show me the changed bytes
  • Repack console/levels/STAGE back into STAGE.AFS

How to install console-levels

1Plugin marketplace

/plugin marketplace add Jakeschincariol/console-skill
/plugin install console-skill@console-skill

This installs the whole console-skill plugin with all its skills

2Skills CLI (Vercel)

npx skills add Jakeschincariol/console-skill --skill console-levels -a claude-code

3Manually: put the files in place

~/.claude/skills/console-levels/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/console-levels/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about console-levels

How do I install console-levels in Claude Code?

Add the marketplace with /plugin marketplace add Jakeschincariol/console-skill, then run /plugin install console-skill@console-skill.

What does console-levels do?

It scans an extracted PS2 disc, splits level archives into numbered entry files with an index.json, and rebuilds them once edited. It also diffs files by byte and reads the port log.

What do I need for console-levels to work?

Python 3 for datascan.py and an extracted PS2 disc image the user dumped personally. Working out level structures involves Ghidra and PCSX2; the files subcommand reads a port run log.

Source text

SKILL.md · MIT
---
name: console-levels
description: >-
  Level Designer. Maps the disc's data files, unpacks the archives the levels live in, and swaps in
  your edits. Inventories an extracted PS2 disc (size, type by magic, entropy, a table-of-contents
  guess with a confidence score), unpacks CRI AFS archives and detected table-of-contents archives
  into a folder with an index.json, repacks them in the same order and alignment (keeping every offset
  when your edits fit), diffs two files or folders to show which bytes a change touched, lists strings,
  and reads the port's log to show which disc files a level loads. Writes under console/ and never
  modifies the original disc files. Use when the user says "where are the levels", "unpack this
  archive", "what's in DATA.BIN", "edit the level", "swap in my map", "what changed between these two
  files", "which files does stage 3 load", or before /console-graphics or /console-sound needs a file
  that sits inside an archive.
argument-hint: "scan|unpack|repack|diff|strings|files <path> [flags]"
---

# console-levels

The Level Designer maps a game's data and gives you a way in. A PS2 disc is a folder of files: the ELF,
IRX modules, and data, usually a few huge archives that hold every level, model, texture and sound.
`datascan.py` tells you what each file is, finds the table of contents inside an archive, splits it
into files you can edit, and puts it back together so the game still reads it. Then the port loads
your edited archive straight from the extracted disc folder, with no ISO to rebuild.

Be honest with the user: every game's level format is its own. This tool gives the map and the knife
(what the files are, how the archives split, which bytes changed). Working out what the bytes inside a
level mean is per game: diff two levels, diff before and after an in-game change, and read the loader
in Ghidra. Compressed or encrypted archives (high entropy everywhere, no table found) need the game's
own decompressor found in its code first.

`${CLAUDE_SKILL_DIR}` below is this skill's folder (where this SKILL.md lives).

```bash
python3 "${CLAUDE_SKILL_DIR}/datascan.py" scan console/disc/ --sort size --embedded     # map the disc
python3 "${CLAUDE_SKILL_DIR}/datascan.py" files console/runs/<newest>.log       # files the port looked up
python3 "${CLAUDE_SKILL_DIR}/datascan.py" unpack console/disc/DATA/STAGE.AFS --out console/levels/STAGE
python3 "${CLAUDE_SKILL_DIR}/datascan.py" diff console/levels/STAGE/files/0003_ST01.DAT console/levels/STAGE/files/0004_ST02.DAT --as f32
python3 "${CLAUDE_SKILL_DIR}/datascan.py" strings console/disc/SLUS_203.12 --grep .afs
python3 "${CLAUDE_SKILL_DIR}/datascan.py" repack console/levels/STAGE --out console/levels/STAGE.AFS
```

Other flags: `--json` everywhere; `scan --min-size N`; `unpack --format afs|toc --layout KIND --header N
--force-toc`; `repack --layout auto|keep|pack --force`; `diff --gap N --max N`; `strings -n N
--encoding ascii|sjis|utf16le|all --max N`. Exit codes: 0 ok, 1 needs attention (no table found, an
entry outgrew its slot, a missing disc file; for `diff`, the inputs differ), 2 bad input.

## What it reads and writes

| path | what |
| --- | --- |
| the extracted disc folder | read only: `scan`, `unpack`, `strings`, `diff` never change it |
| a runtime log (`console/runs/*.log`) | `files` reads the `[sceCdSearchFile:ok]` and `sceCdSearchFile failed:` lines |
| `console/levels/<NAME>/files/` | the unpacked entries, numbered in archive order (`0003_ST01.DAT`) |
| `console/levels/<NAME>/index.json` | format, table layout, alignment, offsets, slot sizes, hashes: everything `repack` needs |
| `console/levels/<NAME>/_header.bin`, `_extra_*.bin` | the archive's header bytes and any bytes outside the entries, kept so a repack is exact |
| `--out` of `repack` | the rebuilt archive (refuses to overwrite an existing file without `--force`) |

Formats, the table detector, AFS details and the index.json schema:
[reference/formats.md](reference/formats.md). Finding what level bytes mean (diffing, Ghidra, PCSX2):
[reference/level-workflow.md](reference/level-workflow.md).

## The method

1. **Map the disc.** `scan <extracted disc> --sort size --embedded`. Note the biggest files, their kind
   and entropy, and any table of contents found (`AFS, N entries` or `count+pairs n=.. (0.9)`). Below
   7.5 bits per byte with a table found: an archive you can split. Above 7.5 everywhere: compressed or
   encrypted; find the decompressor in the ELF before going further.
2. **Find where the levels live.** Run the port into the level (/console-tester `run.py boot`), then
   `files console/runs/<newest>.log` lists the disc files it looked up, in order. The files looked up
   right when the level starts are the level's. `strings <ELF> --grep .bin` (or `.afs`, `stage`, `map`)
   finds file names the code uses. In PCSX2 you can watch the same thing in its log.
3. **Unpack.** `unpack <archive> --out console/levels/<NAME>`. AFS is parsed exactly. Other archives
   use the best table-of-contents guess at confidence 0.6 or more; below that it refuses and says why.
   If you know the layout from Ghidra, force it with `--layout` and `--header`.
4. **Find the structures.** `diff` two levels, or the same level before and after a small change you
   make, with `--as f32` to see coordinates and `--as u16|u32` for counts and ids. Read the loader in
   Ghidra: find the file name string, follow its cross-reference to the code that parses the buffer.
   Write what you learn into `console/design.md` (the game's design doc from /console-reverse).
5. **Edit.** Change the entry files in `console/levels/<NAME>/files/` (same names). Keep sizes when you
   can.
6. **Repack.** `repack console/levels/<NAME> --out console/levels/<NAME>.AFS`. With the default
   `--layout auto`, entries that still fit stay at their exact offsets (the safest result: nothing else
   moves). If one outgrew its slot, offsets are recomputed with the original alignment and the table is
   rewritten; it says so. Use `--layout keep` when the game hard-codes offsets in its code (it then
   refuses rather than move anything). Every repack reads itself back to verify.
7. **Swap it in.** Close the port. Copy the original archive aside (`STAGE.AFS.orig`, or keep it in
   `console/`), copy the repacked one over it in the extracted disc folder. The port reads `cdrom0:\`
   from the ELF's folder (`cdRoot`) and looks files up by name with their real size, so no ISO rebuild.
8. **Playtest.** /console-tester, then load the level. Record what you changed in `console/STATE.md`.

## Guard rails

- **Bring your own game.** Work only on discs you own and dumped yourself (ImgBurn on Windows, `dd`
  from a DVD drive on macOS or Linux). Never download ISOs, ELFs or BIOS files, never help find them,
  never ask for them.
- **Nothing from the game gets published.** Unpacked archives, level files, models, textures and the
  disc itself stay on your machine, like the ELF, the IRX modules and the recompiled C++. Share your
  edits as a patch or a script that changes the user's own files, never the files themselves.
- **Never overwrite your only copy.** `datascan.py` never writes into the disc folder; you copy the
  repacked file in yourself, after keeping the original.
- **Not affiliated with Sony.** PlayStation is a trademark of Sony Interactive Entertainment.

## Hands off to

- /console-graphics for TIM2 textures found inside an archive (`tim2.py` works on unpacked entries).
- /console-sound for VAGs and sound banks found inside an archive.
- /console-physics and /console-mod when the change belongs in code (speeds, rules) rather than data.
- /console-tester to playtest the swapped level and check nothing else broke.

© Jake Schincariol · MIT · Jakeschincariol/console-skill

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set12

The whole set →
console-skill console-skill is a Claude Code plugin with eleven skills for porting PlayStation 2 games you own to native PC builds with PS2Recomp. It covers code analysis, game changes, packaging, and testing. ★ 449repo stars console-saves console-saves is a Claude Code skill that imports PS2 memory card saves into game ports and backs them up. It activates when you ask to migrate PCSX2 saves or sync progress across devices. CX Codex +1 ★ 449repo stars console-physics console-physics is a Claude Code skill that finds game-physics values in an ELF and prints PCSX2 and PS2Recomp patches. It responds to requests about speed, gravity, jumps, grip, camera width, and frame rate. CX Codex +1 ★ 449repo stars console-anywhere console-anywhere is a Claude Code skill that prepares a PS2Recomp build for a target device and packages it for players. It runs on requests to build for Steam Deck, Android, Mac, or another supported target. CX Codex +1 ★ 449repo stars console-sound Console-sound is a Claude Code skill that rips game audio and injects custom tracks back into the files. It decodes PS2 VAG and SPU2 ADPCM formats into WAV for easy editing. CX Codex +1 ★ 449repo stars console-controller console-controller is a Claude Code skill that maps gamepads, keyboard, and touch input into PS2Recomp. It handles remapping, sticks, triggers, and two players. CX Codex +1 ★ 449repo stars console-tester console-tester is a Claude Code skill that automates playtesting for PS2 game ports. It executes ELFs via ps2EntryRunner, categorizes crashes, maps PCs to Ghidra symbols, and diffs PCSX2 dumps. CX Codex +1 ★ 449repo stars console-backend console-backend is a Claude Code skill that ranks missing PS2Recomp backend pieces from runtime logs. It activates after a stop or a request about syscalls, the IOP, or stubs. CX Codex +1 ★ 449repo stars

Project sponsors

Companies that keep this analytics open