How do I install the Compile skill?

Run npx skillmds@latest add jtenniswood/compile in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Compile safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Compile?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Compile free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Compile?

jtenniswood (@jtenniswood) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Compile by jtenniswood — Agent Skill

Name: Compile
Author: jtenniswood

Compile

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.

jtenniswood Updated Sep 17, 2026

File contents

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

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 "/Users/jtenniswood/Library/CloudStorage/Dropbox/Git/espcontrol:/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 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:

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.

---name: compiledescription: 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 DevicesCompile ESPHome firmware for every device in the repo using Docker. If a buildfails, diagnose the error, fix the source YAML, and re-compile until alldevices pass.## Device Slugs```textguition-esp32-p4-jc1060p470guition-esp32-p4-jc4880p443guition-esp32-s3-4848s040```## Workflow### 1. Resolve the ESPHome VersionUse the ESPHome version pinned by the repository in `.github/esphome.env`. Thisis the same version used by CI and release builds; do not hard-code an olderversion in this skill.```bashESPHOME_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 DeviceRun one Docker compile per device. Use `builds/<slug>.factory.yaml`, the sameentry point CI uses, so the test matches what a release build would do.```bashdocker run --rm \ -v "/Users/jtenniswood/Library/CloudStorage/Dropbox/Git/espcontrol:/config" \ "$ESPHOME_IMAGE" \ compile /config/builds/<slug>.factory.yaml```Run devices sequentially because each compile is resource-intensive. Use a10-minute timeout or block window when available so compiles are not treated asstalled too early. If a compile backgrounds, poll the terminal output until itfinishes and read the result.If the pinned image is missing, pull it first:```bashdocker 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 FailureWhen 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 mustcompile.Fixes should target files under `common/`, `devices/`, or `components/` whenpossible, not the `builds/*.yaml` wrappers because those are thin entry points.### 5. Web UI Asset NoteThe factory YAML bundles `www.js` via `js_include`. If the referenced JavaScriptfile is missing, compile will fail. Run this first when web UI assets may be outof date:```bashpython3 scripts/build.py```### 6. ReportAfter all devices pass, summarize:```textCompile results: guition-esp32-p4-jc1060p470 OK guition-esp32-p4-jc4880p443 OK guition-esp32-s3-4848s040 OKFixes applied: - <file>: <what was wrong and what was changed>```If no fixes were needed, show only the passing results.

Frequently asked questions