SGDK Skills

Practical agent skills for making Sega Mega Drive and Genesis games with SGDK. Build through the SGDK Docker toolchain, keep your project on your computer, and use an agent to help with setup, assets and debugging.

The playable Labs demonstrate techniques, not designs to copy. Your game’s rules, flow, controls, art and music come from your brief. Use a Lab to examine a specific solution; building a new game does not mean starting from its code.

For Sega CD development, see Megadev Docker and Megadev Skills (in development).

Skills

Get started

Build your game

Game genres

Test, debug and optimize

Ship your game

Install

Use Skills CLI to choose the skills and agents you want:

npx skills add ewrogers/sgdk-skills

To list the collection or install just one:

npx skills add ewrogers/sgdk-skills --list
npx skills add ewrogers/sgdk-skills --skill sgdk-project

The current installer needs Node.js 22.20 or later. Planning works without Docker. The build workflow needs Docker running with Linux containers. The optional helpers need Python 3.10+ and use its standard library. No native SGDK installation or API key is needed.

Use

Ask your agent to use a skill for a concrete task. For example:

• “Use sgdk-project to create a Hello World ROM in a new folder.”
• “Use sgdk-planning to plan a small platformer and identify what to prove first.”
• “Use sgdk-best-practices to review this module’s arithmetic, ownership and failure handling.”
• “Use sgdk-assets to import this spritesheet and check its palette budget.”
• “Use sgdk-pixellab to generate palette-cohesive native sprites and validate their exports.”
• “Use sgdk-graphics to animate a character over a scrolling background with a fixed HUD.”
• “Use sgdk-animation to add attack phases, timed cues, interruption and one-hit-per-action hitboxes.”
• “Use sgdk-effects to add explosions, weather and camera shake without crowding out gameplay sprites.”
• “Use sgdk-raster to add underwater ripples and a palette switch below a moving waterline.”
• “Use sgdk-audio to add music, prioritized effects and a pause-menu transition.”
• “Use sgdk-input to add 3/6-button pad and mouse controls, with Team Player support.”
• “Use sgdk-multiplayer to add four-player co-op with joining, shared framing and independent respawns.”
• “Use sgdk-ui to add a title screen, options, pause menu and fixed score display.”
• “Use sgdk-localization to add French and Spanish menus with accented glyphs and translated layout checks.”
• “Use sgdk-dialogue to add a portrait conversation with gradual text and branching choices.”
• “Use sgdk-levels to import a Tiled level with scrolling, walls and camera limits.”
• “Use sgdk-isometric to build an elevated courtyard with correct above/below bridge ordering.”
• “Use sgdk-streaming to preload area art with a bounded tile cache while keeping the hero and HUD resident.”
• “Use sgdk-compression to compare RAW, APLIB and LZ4W for room art and preload it before use.”
• “Use sgdk-gameplay to add a scrolling player, wall collision and reusable bullets.”
• “Use sgdk-shmup to build a scrolling shooter with readable bullet patterns, upgrades and a boss.”
• “Use sgdk-platformer to build a responsive scrolling course with wall jumps, stomps and secrets.”
• “Use sgdk-puzzle to build a push-and-switch board with undo, or a falling-block game with tested rotation and row clearing.”
• “Use sgdk-rpg to add a party, validated combat actions, status effects, equipment and battle rewards.”
• “Use sgdk-collision to stop fast bullets tunnelling through walls and slide a player along obstacles.”
• “Use sgdk-combat to connect attack contacts to fair damage, guard and hit reactions.”
• “Use sgdk-math to build a fixed-point starfield and orbiting formations.”
• “Use sgdk-cartridge to load stage graphics and music from separate ROM banks while keeping shared assets pinned.”
• “Use sgdk-save to add checkpoint saves, a backup slot and password entry.”
• “Use sgdk-memory to track RAM, diagnose a failed allocation and prove room cleanup restores the baseline.”
• “Use sgdk-performance to measure a busy scene and optimize it without changing gameplay.”
• “Use sgdk-debug to investigate this fault using the matching ELF file.”
• “Use sgdk-testing to replay this route and catch regressions in both PAL and NTSC schedules.”
• “Use sgdk-hardware to prepare console checks and distinguish emulator observations from hardware evidence.”
• “Use sgdk-release to validate and package this release candidate without changing the ROM.”

Each skill works on its own. It includes focused references and, where useful, a helper or small example. Agents check the selected container’s headers, manuals and samples before proposing unfamiliar API calls. The default is ewrogers/sgdk:latest. Pull it before building, and check the installed SDK’s version when consulting the references.

The guidance accounts for CPU work, RAM, VRAM, palettes, sprite scanlines and transfer bandwidth separately. It helps you use SGDK directly and leaves your game’s architecture to you.

Planning includes an optional static budget checker for RAM, VRAM, palettes, sprite peaks, padded ROM size and a declared DMA allowance. It keeps unknown costs visible. It does not predict frame rate or certify that a game will fit.

The references also cover cartridge mapping and padding, 68000 assembly investigations, Z80 bus ownership and FM/PSG interactions. They link to the selected SGDK source and Plutiedev for deeper hardware explanations, rather than treating every build as a low-level driver project.

Tested support

Host helpers are tested on Windows, macOS and Linux. ROM/resource examples are built on native Linux ARM64 and AMD64; Docker Desktop supplies the Linux environment on other hosts. Windows Docker runtime testing is still separate from the host helper checks.

Build tests check API compatibility, resources and diagnostics. They do not prove correct visuals, sound or frame timing. Those need emulator or console testing. See testing and maintenance for checks, image updates and the exact validation boundaries. The composition milestone also checks several skills together in a new disposable game, rather than only rebuilding the Labs. Its streaming/audio follow-up checks bounded uploads, palette publication and asynchronous music handoffs together. The design-adaptation test gives an independent agent a contrasting game brief, then reviews technique reuse and whether the Labs’ designs carried over.

The skills and original examples are MIT licensed. SGDK and the bundled toolchain retain their own licenses.

Disclaimer

SGDK Skills is an independent community project. It is not affiliated with, endorsed by or sponsored by SEGA CORPORATION or SEGA SAMMY HOLDINGS INC. SEGA and related names, logos and trademarks belong to their respective owners. They are used here to identify the hardware and tools this project supports.

This repository’s original work is available under the MIT License. Third-party software and materials retain their own licenses and notices.