crosspad-mcp: Skill for Claude Code

CrossPad PC iteration loop

The MCP server already tells the agent which tools exist (see server instructions). This skill encodes how to chain them into a tight edit→verify loop without thrashing — and how to recover when one of the four common failure modes hits.

The loop

edit source
  → crosspad_check          (decide build mode + spot drift)
  → crosspad_kill           (free port 19840 before respawn)
  → crosspad_build           (mode chosen from check)
  → crosspad_run             (inspect responsive flag)
  → crosspad_screenshot / _input / _stats / _log   (verify)
  → repeat or crosspad_kill

Run crosspad_kill before crosspad_build when a sim is alive. The build itself succeeds either way, but the running binary's text segment is still mapped — kill after the rebuild works (the tool strips the kernel's " (deleted)" suffix from /proc/<pid>/exe), but run will refuse to spawn a duplicate while the old one holds port 19840. Killing first keeps the loop linear.

Build mode decision

Read crosspad_check output and pick:

Check signal	Mode	Why
needs_reconfigure: true (new source files, missing CMakeLists, no build/)	reconfigure	CMake GLOB_RECURSE won't pick up new .cpp files until cmake reruns
needs_rebuild: true only (sources newer than exe, submodule HEAD drift, dirty submodule)	incremental	Default; ninja figures out the deltas
Toolchain change, vcpkg update, weird link errors after a working build	clean	Nukes build/ — last resort, costs minutes
reasons: ["Build appears up to date"]	skip build	Just crosspad_run

build_type: Debug is the default and what you want for the loop. Switch to Release only when profiling.

Diagnosing the four common failures

crosspad_run returns already_running: true — another sim is bound to TCP 19840. Run crosspad_kill first; do not pass force: true blindly (two sims clobber each other's window state and you'll get garbage from screenshot/stats).