Skip to content

jtenniswood/espcontrol / .agents/skills/compile

compile

Verified

Test 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.

FileKindSize
SKILL.mdskill md3.6 KB
---
name: compile
description: >-
  Test 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

```text
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:

```bash
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.

```bash
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.

```bash
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:

```bash
docker pull "$ESPHOME_IMAGE"
```

### 3. Interpret Results

- Success: output ends with `Successfully compiled program` or
  `INFO Successfully compiled program.`
- Failure: inspect `ERROR` lines and the file/line references around them.

Common failure categories:

- YAML syntax errors, including indentation and missing keys
- Missing `!include` targets 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:

1. Read the full error output carefully.
2. Identify the failing file and line from the error message.
3. Open and read that file to understand context.
4. Fix the root cause in source YAML.
5. Re-run the same Docker compile command for that device.
6. 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:

```bash
python3 scripts/build.py
```

### 6. Report

After all devices pass, summarize:

```text
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.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall