pokemon-player

Plays Pokemon games via headless PyBoy emulation with RAM state reads and screenshot verification.

Updated Apr 13, 2026
One-click install
npx skills add https://github.com/xiaoshan1234/ai-skill --skill pokemon-player-xiaoshan1234
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: pokemon-player
Source: https://github.com/xiaoshan1234/ai-skill/tree/main/origin/pokemon-player
Command: npx skills add https://github.com/xiaoshan1234/ai-skill --skill pokemon-player-xiaoshan1234

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pokemon-agent, pyboy.

What problem does it solve? Playing Pokemon through an emulator requires constant visual attention and manual input; this Skill automates gameplay by combining headless emulation, RAM state inspection, and screenshot-based vision so an AI can navigate, battle, and progress through the game autonomously. ## Core Features & Use Cases - Headless Game Server: Runs the pokemon-agent server with a ROM file, exposing REST endpoints for state, screenshots, actions, and save/load management. - Observe-Decide-Act Loop: Combines RAM reads (position, HP, battle, dialog) with vision analysis of screenshots to navigate maps, handle dialog, and fight battles reliably. - Save State Management: Saves progress before risky encounters like gym battles and resumes from named save states on startup. - Use Case: A user says "play pokemon" and the AI starts Pokemon Red, sets up a live dashboard via an SSH tunnel so the user can watch, then plays through milestones like earning the Boulder Badge while saving progress every 15-20 turns. ## Quick Start Say "play pokemon" and provide your own Pokemon ROM file so the game server can start and the live dashboard link can be shared with you.

Frequently Asked Questions about pokemon-player

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I play Pokemon with an AI using a headless emulator?▼

Start the pokemon-agent server with your ROM file using the serve command on port 9876, then follow the observe-decide-act loop: read RAM state, take screenshots, and send short action sequences. The Skill handles navigation, battles, and saving automatically.

How do I set up the pokemon-agent game server?▼

Clone the NousResearch/pokemon-agent repository, create a Python 3.10+ virtual environment with uv or venv, and install the package with the pyboy extra. Then run pokemon-agent serve with --rom pointing to your ROM and --port 9876.

Can I watch the AI play Pokemon in my browser?▼

Yes, the Skill sets up an SSH reverse tunnel through localhost.run that forwards the local dashboard port to a public URL. You receive a .lhr.life link with /dashboard/ appended, though the URL changes each time the tunnel restarts.

Does the Pokemon player provide ROM files?▼

No, the Skill never downloads or provides ROM files. You must supply your own legally obtained ROM file (.gb, .gbc, or .gba) before the game server can start.

Why does the AI get stuck or lost while navigating in Pokemon?▼

RAM state only reports position and HP, not surroundings like ledges, doors, or NPCs, so movement without screenshots causes disorientation. The Skill mitigates this by taking screenshots every 2-4 steps and waiting extra frames after warp transitions.

How does save and load work in the Pokemon emulator?▼

Save states are created with POST /save using a descriptive name and restored with POST /load or the --load-state startup flag. The Skill saves every 15-20 turns and always before gym battles or risky encounters.