ESP32 Agent Skills
A practical ESP32 engineering toolkit for AI coding agents: curated skills, hardware-aware guardrails, and command-line validation tools that catch mistakes before a board is flashed.
Read the project site →
Why this exists
AI coding agents can write ESP32 firmware that compiles cleanly and still fails on hardware. The most common failures are not logic bugs; they are hardware constraints hidden in the pin map, boot settings, power budget, and protocol boundaries.
Examples:
- GPIO6 tied to SPI flash
- GPIO34 used as an output when it is input-only
- GPIO12 held high during reset on a 3.3 V flash board
- ADC2 readings failing while Wi‑Fi is active
This repository gives the agent the missing knowledge and gives the workflow a check that runs before flashing.
What is included
- Skills for ESP32 architecture, GPIO, power, memory, OTA, Wi‑Fi/BLE, Modbus, CAN, sensors, debugging, and industrial interfaces
- Hardware-focused validation tools for common failure modes
- Agent-installation support for multiple harnesses and plugins
- Example boards, test data, and engineering references
Quick start
Clone and validate a pin map:
git clone https://github.com/Esmail-sarhadi/esp32-agent-skills.git
cd esp32-agent-skills
python tools/pincheck.py --soc esp32 --assign "12=relay,34=button,25=led"
Example output:
ESP32 (classic, WROOM-32 / WROVER) - 3 pin(s) checked
GPIO6 ERROR status_led GPIO6 is connected to the SPI flash, using it bricks the module
GPIO12 WARN relay1 GPIO12 is a strapping pin and must be LOW at boot on 3.3 V flash
modules, HIGH selects 1.8 V and the board will not boot
GPIO34 WARN button GPIO34 is input-only: it cannot drive an output and has no internal
pull-up or pull-down
1 error(s), 2 warning(s)
Check a partition layout:
python tools/partition_check.py --file examples/partitions-ota-4mb.csv --flash 4MB --ota
Check the power budget:
python tools/power_budget.py --battery 3000 --wakes-per-hour 12 --wake-ms 2000
Install as an agent skill
This repository follows the skill layout used by agent toolchains, with content split between short operational guidance and longer reference material.
Claude Code plugin
/plugin marketplace add Esmail-sarhadi/esp32-agent-skills
/plugin install esp32-agent-skills
Local harness install
./install.sh --harness claude
./install.sh --harness codex
./install.sh --harness opencode
./install.sh --harness all
PowerShell variants are also provided:
./install.ps1 -Harness codex
./install.ps1 -Harness all -DryRun
See harnesses/README.md for supported locations and capability boundaries.
Included tools
| Tool | Purpose |
|---|
tools/pincheck.py | Validate GPIO usage against ESP32 SoC constraints |
tools/partition_check.py | Check partition layout and OTA alignment |
tools/power_budget.py | Estimate runtime and dominant current draw |
tools/panic_decode.py | Decode crash dumps and backtraces |
tools/airtime.py | Check LoRa airtime and duty-cycle feasibility |
tools/modbus_map_check.py | Validate Modbus register maps |
tools/modbus_frame.py | Validate RTU framing and timing |
tools/mqtt_topic_check.py | Validate MQTT topic filters and naming |
tools/flash_layout.py | Detect overlapping firmware or flash regions |
tools/i2c_address_check.py | Detect duplicate or reserved I²C addresses |
tools/esp32_skills_cli.py | One entry point for every checker in the repository |
tools/render_pin_table.py | Render data/esp32-pins.json into a human-readable reference table |
tools/gen_manifest.py | Generate agent.yaml and plugin manifests from the skills directory |
tools/gen_readme_catalog.py | Regenerate the skills catalog in this README from SKILL.md frontmatter |
tools/validate_skills.py | Validate every SKILL.md against schemas/skill.schema.json |
Skills catalog
The repository now contains 644 skills. The latest 400-skill expansion is indexed in docs/advanced-skill-expansion.md.
Generated by tools/gen_readme_catalog.py from each SKILL.md frontmatter. Do not edit the table by hand.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
