jtenniswood/espcontrol / .agents/skills/compile
compile
VerifiedTest compile ESPHome firmware for all devices using Docker and fix any YAML or configuration errors until every device compiles successfully. Use when the user says "/compile", "test compile", "compile check", "build test", "check builds", "verify compile", or wants to make sure all devices compile before committing.
Test Compile - Build All Devices
Compile ESPHome firmware for every device in the repo using Docker. If a build fails, diagnose the error, fix the source YAML, and re-compile until all devices pass.
Device Slugs
guition-esp32-p4-jc1060p470
guition-esp32-p4-jc4880p443
guition-esp32-s3-4848s040
Workflow
Run all commands from the active repository worktree. Resolve its root once and use that path for Docker mounts; do not use a fixed machine-specific checkout path:
REPO_ROOT="$(git rev-parse --show-toplevel)"
1. Resolve the ESPHome Version
Use the ESPHome version pinned by the repository in .github/esphome.env. This
is the same version used by CI and release builds; do not hard-code an older
version in this skill.
ESPHOME_VERSION="$(sed -n 's/^ESPHOME_VERSION=//p' .github/esphome.env)"
test -n "$ESPHOME_VERSION"
ESPHOME_IMAGE="ghcr.io/esphome/esphome:${ESPHOME_VERSION}"
Keep these variables in the shell session used for the compile commands.
2. Compile Each Device
Run one Docker compile per device. Use builds/<slug>.factory.yaml, the same
entry point CI uses, so the test matches what a release build would do.
docker run --rm \
-v "$REPO_ROOT:/config" \
"$ESPHOME_IMAGE" \
compile /config/builds/<slug>.factory.yaml
Run devices sequentially because each compile is resource-intensive. Use a 10-minute timeout or block window when available so compiles are not treated as stalled too early. If a compile backgrounds, poll the terminal output until it finishes and read the result.
If the pinned image is missing, pull it first:
docker pull "$ESPHOME_IMAGE"
3. Interpret Results
- Success: output ends with
Successfully compiled programorINFO Successfully compiled program. - Failure: inspect
ERRORlines and the file/line references around them.
Common failure categories:
- YAML syntax errors, including indentation and missing keys
- Missing
!includetargets or wrong relative paths - Unknown component or platform
- Undefined substitution variables
- Type mismatches, such as a string where an integer is expected
- Missing
packages:keys
4. Fix and Retry on Failure
When a device fails:
- Read the full error output carefully.
- Identify the failing file and line from the error message.
- Open and read that file to understand context.
- Fix the root cause in source YAML.
- Re-run the same Docker compile command for that device.
- Repeat until it succeeds, then move to the next device.
Do not skip a device or mark it as known broken. Every listed device must compile.
Fixes should target files under common/, devices/, or components/ when
possible, not the builds/*.yaml wrappers because those are thin entry points.
5. Web UI Asset Note
The factory YAML bundles www.js via js_include. If the referenced JavaScript
file is missing, compile will fail. Run this first when web UI assets may be out
of date:
python3 scripts/build.py
6. Report
After all devices pass, summarize:
Compile results:
guition-esp32-p4-jc1060p470 OK
guition-esp32-p4-jc4880p443 OK
guition-esp32-s3-4848s040 OK
Fixes applied:
- <file>: <what was wrong and what was changed>
If no fixes were needed, show only the passing results.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |