Build1 publisher3 min readPublished
Per-board skill directories for Claude Code aim to capture pin maps and hardware gotchas
Model-written firmware compiled first try, flashed clean, and put colored noise on the panel because the cropped glass needs a drawing-window offset that only the vendor's wiki documents. A new repo packages that fact per board.
The Engineer · Build desk
What happened
- Model-written display code compiled and flashed cleanly but showed noise: the ST7789 addresses 240x320 while the board's glass shows 172x320, so the driver must offset the drawing window by 34 pixels.
- Other traps listed include Pico GPIO23, 24, 25 and 29 missing from the 40-pin header, ESP32 ADC2 timing out while Wi-Fi runs, and an STM32F411 at 100 MHz instead of 96 MHz silently killing USB.
- The author is publishing one Claude Code skill per board, eight so far, each with an always-loaded SKILL.md, an on-demand reference directory and a template project that builds and flashes.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- constraint The compiler and the flasher both pass on these bugs, so an agent loop that iterates on build errors has no signal to iterate on; the only oracle is the board on the bench.
- cost Each board in the collection costs someone the purchase and the debugging evening behind it, so coverage grows only as fast as hardware gets bought and probed.
- decision Embedded teams now have a concrete choice between live search, which burns context and can return the wrong board revision, and a static skill snapshot tied to one project that flashed.
- precedent Extracting every line of context from a working build sets a testable standard for hardware context packs: the file can be regenerated from the template, and drift shows up as a build that fails.
The offset comes straight out of the geometry. The ST7789 addresses a 240x320 frame; the glass on the board shows 172x320. The visible window sits in the middle of controller memory, so (240 - 172) / 2 leaves 34 hidden columns on each side [1]. Skip the offset and the image shifts sideways, a third of the content lands past the edge of the glass, and garbage creeps in from the other side [3].
Code written for a 240x320 ST7789 is correct code for a 240x320 ST7789, and the compiler will happily emit it for a panel you do not own. No reasoning failed. The board-specific part is the offset, the required color inversion and the big-endian byte order, which the post says sit in the vendor's wiki between two fine-print warnings and in no tutorial [4].
Firmware also puts these failures past every automatic check an agent has. The generated code compiles on the first attempt and flashes without errors [1]. A Pico project that drives GPIO23, 24, 25 or 29 compiles, flashes and appears to work, and those pins are not on the 40-pin header [6]. ESP32 ADC2 returns a timeout whenever the radio is up [7]. On the STM32F411, HAL_Delay() hangs when nobody defined SysTick_Handler, which the post calls documented almost nowhere [8]. A build-and-fix loop reads green on all four.
The author's diagnosis is stated plainly: "At its core, this is a missing-context problem." [16] The layout that follows is a context budget. SKILL.md is always loaded and holds the pin map, chip characteristics and the rules that prevent costly mistakes. reference/ holds the full pinout with alternate functions, peripherals and a table of gotchas, and it loads on demand [11]. The alternative he reports trying, a web search MCP, helps somewhat but burns context on every small lookup and turns up tutorials written for a different revision of the board [14].
Call it a provenance rule: template/ is a project that builds and flashes, and every line of the skill is extracted from it instead of written from memory [12]. The skill therefore describes a build that ran on the hardware.
Eight boards are in now: two STM32s, four ESP32s, the Arduino Nano on ATmega328P and the RP2040, which accounts for all eight [13][2]. Those are boards from the author's own collection [9]. That is the limit on coverage. The post does not report any measurement of firmware task outcomes with and without a skill [17], so the argument for the approach rests on the named failure modes: the shared SPI bus on the Waveshare ESP32-C6-LCD-1.47. Display and microSD share MOSI on GPIO6 and SCLK on GPIO7, and a model that splits them produces a conflict that looks like a dead memory card [5].
install.sh takes a board name, and Claude Code picks the skill up when you work with that board. /stm32f411-blackpill invokes it explicitly. Copying the directory into .claude/skills/ scopes it to one firmware project [15].
What to watch
- Whether the repository ever publishes before-and-after results for firmware tasks run with and without a board skill.
- Whether skills get pinned to board revisions, given the author's warning that search turns up tutorials for a different revision.
- Whether coverage grows past the eight boards the author owns, and who supplies the bench time for boards he does not.