pyxel-skill: агентский навык для разработки ретро-игр на Pyxel с проверкой через MCP

Написать игру на Pyxel — дело несложное. Проверить, что она работает, — куда сложнее. Игра рисует пиксели, откликается на нажатия и падает с ошибкой, которую не видно в коде. Агент без специальных инструментов в такой ситуации рассуждает наугад: он может написать двадцать строк игровой логики и ни разу не увидеть результат.

Навык pyxel-skill закрывает этот пробел. Он заставляет агента смотреть на игру. Отдельный MCP-сервер pyxel-mcp запускает код в headless-режиме, прокручивает кадры, подставляет нажатия клавиш и отдаёт то, что получилось: снимки экрана, состояние объектов, сетку пикселей, записи звука. Навык объясняет агенту, в каком порядке это делать и что именно считать доказательством.

Сейчас вышла версия 1.4.2. Она рассчитана на pyxel-mcp не ниже 1.3.1, Pyxel не ниже 2.9.6 и Python не ниже 3.11.

Что лежит в репозитории

• SKILL.md — когда включаться, как настроить окружение, порядок работы и проверки, а также чёткие границы.
• references/pyxel.md — поведение Pyxel: ввод, отрисовка, ассеты, звук, повторяемые прогоны.
• references/design.md — как подать игру: сцена, обратная связь, игровой поток.
• references/strict-mode.md — расширенная проверка для релизов, аудитов и отчётов с доказательствами.
• LICENSE — MIT.

Справочные файлы короткие, и это осознанно. Агент читает их только когда задача касается их темы, а не весь объём сразу.

Установка

Claude Code

Репозиторий одновременно является плагином. Он сразу подключает и навык, и MCP-сервер:

claude plugin marketplace add kitao/pyxel-skill
claude plugin install pyxel@pyxel-skill

Плагин регистрирует сервер pyxel командой uvx --from 'pyxel-mcp>=1.3.1' pyxel-mcp, поэтому добавлять сервер руками не нужно. Навык доступен как /pyxel:pyxel и включается сам, когда речь идёт о работе с Pyxel.

Любой агент с skills CLI

npx skills add kitao/pyxel-skill

Клиенты без автоматической регистрации плагинов дополнительно настраивают MCP-сервер — об этом ниже.

Вручную

Папка или симлинк с навыком должны называться pyxel:

git clone https://github.com/kitao/pyxel-skill.git .claude/skills/pyxel
rm -rf .claude/skills/pyxel/.git

Один клон можно расшарить на всех агентов через симлинки:

git clone https://github.com/kitao/pyxel-skill.git ~/src/pyxel-skill

# Agent Skills
mkdir -p ~/.agents/skills && ln -s ~/src/pyxel-skill ~/.agents/skills/pyxel

# Codex
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" && ln -s ~/src/pyxel-skill "${CODEX_HOME:-$HOME/.codex}/skills/pyxel"

# Claude Code
mkdir -p ~/.claude/skills && ln -s ~/src/pyxel-skill ~/.claude/skills/pyxel

Настройка MCP

Для клиента, который не умеет ставить плагины, команда install печатает готовые инструкции — она ничего не меняет сама:

uvx --from 'pyxel-mcp>=1.3.1' pyxel-mcp install

Дальше нужно применить инструкцию для своего клиента, заменив в ней uvx pyxel-mcp на uvx --from 'pyxel-mcp>=1.3.1' pyxel-mcp. Для Codex CLI это делается так:

codex mcp add pyxel -- uvx --from 'pyxel-mcp>=1.3.1' pyxel-mcp

Ограничение версии стоит здесь не для красоты: без него uvx возьмёт уже установленную старую версию пакета. Если сервер зарегистрирован, нужно обновить его текущую команду, а для плагина — обновить сам плагин. После перезапуска клиента pyxel_info должен показать версию 1.3.1 или новее.

Восемь инструментов наблюдения

Сервер отдаёт факты, а оценивать их должен сам агент.

Порядок работы

Навык задаёт пять шагов, и это главная его ценность.

1. Разобраться в задаче. Найти нужное поведение и то, какой существующий код и ассеты оно затрагивает. Для новой игры сразу выбрать играбельный объём: управление, цель, состояние поражения и повтора, если они нужны по правилам.
2. Реализовать. Держаться принятых в проекте соглашений по ассетам, не изобретать свой формат.
3. Прогнать validate, затем run. Ошибки исправить, предупреждения разобрать или объяснить. Задание нажатий давать расписанием, а при наличии случайности — передавать random_seed. Проверить, что игра дошла до нужной остановки без падения, таймаута и зависания, и прочитать log даже тогда, когда ok равен true.
4. Посмотреть глазами. Проверить состояние по предикатам задачи и отдельно осмотреть сами кадры: картинку удобно смотреть через screen_image с inline: true. Для новой игры нужны и то, и другое. Звук проверяется через read_audio — и слушать нужно тоже, одной проверки фактов мало.
5. Отчитаться. Перечислить изменённые файлы, результаты проверок и то, что осталось непроверенным. Поведение, увиденное фактами, нужно отличать от суждений по картинке и на слух.

Отдельно в навыке закреплены границы, которые ломают чаще всего: нельзя принять сломанный кадр только потому, что состояние проверилось; нельзя требовать отчёты с доказательствами для обычных правок; нельзя подменять заказанную спрайтовую графику прямоугольником, если простая геометрия не была задумана как стиль.

Мелочи Pyxel, на которых спотыкаются

Большая часть справочника — про ошибки, невозможные без практики.

Ввод. pyxel.btn(KEY) возвращает нажатие постоянно, pyxel.btnp(KEY) — только в момент нажатия. Чтобы нажать одну клавишу, удерживая другую, в расписании указывают ["KEY_RIGHT", "KEY_SPACE"] на одном кадре и ["KEY_RIGHT"] на следующем. Событие buttons заменяет весь набор нажатых клавиш и действует дальше, поэтому отпустить всё — это buttons: [].

Повторяемость. Если случайность влияет на результат, run всегда получает random_seed. Он запускает генератор Pyxel и стандартный random, включая момент импорта модуля. Собственные экземпляры random.Random нужно засеивать отдельно.

Проверка состояния. Пути attrs — это атрибуты объекта приложения (player.x, enemies[0].y), а не выражения. Вычисляемое доказательство стоит вынести в отдельный атрибут.

Зависания. stall_window_frames останавливает прогон, когда состояние или сетка пикселей повторяются столько кадров подряд. Это позволяет поймать заморозку, не дожидаясь конца бюджета кадров.

Картинки. screen_image с inline: true возвращает PNG прямо в ответе, а масштаб 2–4 делает пиксель-арт читаемым. Файл при этом всё равно пишется, и его потом можно сравнить через diff_frames. Явные пути обязаны быть абсолютными, скриншоты заканчиваются на .png, а несколько кадров требуют output_pattern с буквальным {frame}. За один вызов приходит не больше 12 картинок — остальные остаются на диске, и отдельная текстовая заметка в ответе об этом сообщает.

Отрисовка. В начале draw() вызывают pyxel.cls(color), если сохранение пикселей не задумано. Когда индекс 0 палитры прозрачный, в blt() передают colkey=0. Логика живёт в update(), а draw() только показывает текущее состояние.

Ассеты. Данные изображений и тайлмапов готовят до pyxel.run() — обычно в App.__init__. Спрайты, нарисованные кодом, задаются так: pyxel.images[0].set(x, y, ["01100110", ...]), по одной шестнадцатеричной цифре на пиксель. Относительные пути вроде pyxel.load("assets/game.pyxres") считаются от папки скрипта.

Звук. Звуки задают через pyxel.sounds[N].set(...). В строке нот указывается октава — например, C2D2E2, а R означает паузу.

Строгий режим

Для обычных правок он не нужен. Он включается, когда просят релизную проверку, аудит или отчёт с доказательствами. Тогда навык требует пройти все достижимые ветки: успех, поражение, повтор и отклонённые действия — по реальным правилам игры. Для головоломки это решаемый маршрут и неверный ход, для экшена — последствия столкновения и восстановление после него.

Отдельно проверяются звук и музыка: их нужно отрисовать и убедиться, что нужные события в игре действительно их вызывают. Успешная отрисовка и удачное на слух звучание — это разные вещи, и путать их нельзя.

Сохранённые доказательства тоже делают выборочно: только то, что поддерживает проверку. Это несколько характерных кадров с явными путями, запись движения или звука там, где без них не обойтись, и отчёт с управлением, командами воспроизведения, наблюдаемыми результатами и ограничениями. Отдельный файл отчёта создают, только когда его попросили или он нужен дальнейшей работе.

Совместимость

История изменений — в CHANGELOG.md. Лицензия MIT.