Claw ESP Expert

Use this skill when the user needs help with ESP-IDF environment checks, example discovery, pin safety review, or build diagnostics.

What this bundle includes

This ClawHub-facing bundle exposes nine stable MVP tools:

• manage_env
• explore_demo
• resolve_component
• analyze_partitions
• decode_panic
• analyze_monitor
• flash_and_monitor
• execute_project
• safe_build

These tools are implemented in the bundled runtime and are invoked through scripts/run-tool.mjs.

Safety contract

• Treat this skill as a diagnostic-first ESP-IDF expert.
• Default to check and explain, not silent modification.
• Do not claim support for fully autonomous repair, deep serial-port management, or HIL automation unless the repository actually implements them.
• Do not invent additional tools beyond the ones listed in this file.
• Do not read arbitrary local config files unless the user explicitly asks; the MVP bundle does not require VS Code config scanning.
• Do not modify project files or system permissions unless the user clearly asks for that action.

Tool contract

manage_env

Purpose:

• inspect local ESP-IDF availability
• report $IDF_PATH, common install paths, python/python3, and idf.py availability
• when explicitly asked, return mirror-aware manual installation guidance instead of running upstream install scripts automatically

Example invocation:

printf '%s' '{"action":"check"}' | node scripts/run-tool.mjs manage_env --stdin

explore_demo

Purpose:

• inspect local $IDF_PATH/examples
• find matching demos by keyword
• read the best matching README.md / README_CN.md
• summarize hardware requirements and structure

Example invocation:

printf '%s' '{"query":"gpio"}' | node scripts/run-tool.mjs explore_demo --stdin

safe_build

Purpose:

• run GPIO safety audit before build
• reject fatal pin conflicts early
• invoke idf.py build only after the audit passes
• return structured build diagnostics, including partition overflow, memory overflow, missing headers, component resolution failures, config issues, and link errors

Example invocation:

printf '%s' '{"projectPath":"/path/to/project","chip":"esp32"}' | node scripts/run-tool.mjs safe_build --stdin

analyze_partitions

Purpose:

• parse partitions.csv from the current ESP-IDF project
• identify the most likely app partition (factory / ota_0)
• combine partition table data with overflow logs
• return a recommended expanded partition size and an updated CSV draft
• return a structured patch-style before/after suggestion for partitions.csv

Example invocation:

printf '%s' '{"projectPath":"/path/to/project","rawLog":"Part '\''factory'\'' ... overflow 0x20000"}' | node scripts/run-tool.mjs analyze_partitions --stdin

decode_panic

Purpose:

• parse ESP-IDF panic logs
• extract exception reason, registers, and backtrace addresses
• call the correct addr2line tool for Xtensa or RISC-V chips
• return decoded source locations from the ELF file

Example invocation:

printf '%s' '{"chip":"esp32s3","elfPath":"/path/to/app.elf","log":"Guru Meditation Error..."}' | node scripts/run-tool.mjs decode_panic --stdin

analyze_monitor

Purpose:

• inspect raw idf.py monitor output
• detect panic/backtrace markers automatically
• return the recent log excerpt
• trigger panic decoding when an ELF path is available

Example invocation:

printf '%s' '{"chip":"esp32s3","elfPath":"/path/to/app.elf","log":"...monitor output..."}' | node scripts/run-tool.mjs analyze_monitor --stdin

flash_and_monitor

Purpose:

• run idf.py flash monitor
• capture combined stdout/stderr
• analyze the resulting monitor log
• automatically trigger panic decoding when panic markers appear and an ELF path is available
• return stage status, stage summary, timeout info, recent log tail, and common serial/tool failure categories

Example invocation:

printf '%s' '{"projectPath":"/path/to/project","chip":"esp32s3","port":"/dev/ttyUSB0"}' | node scripts/run-tool.mjs flash_and_monitor --stdin

execute_project

Purpose:

• run the minimum execution loop for an ESP-IDF project
• perform hardware audit first
• build the project
• then run flash_and_monitor
• return a single structured result for the whole flow

Example invocation:

printf '%s' '{"projectPath":"/path/to/project","chip":"esp32s3","port":"/dev/ttyUSB0"}' | node scripts/run-tool.mjs execute_project --stdin

resolve_component

Purpose:

• query the official ESP Component Registry
• prefer espressif/* when an official component is a strong match
• suggest the best-matching component from official registry data
• generate a minimal idf_component.yml dependency snippet
• optionally merge that dependency into an existing manifest draft
• return a structured patch-style before/after suggestion for the manifest
• surface component docs, supported targets, and the matching version

Example invocation:

printf '%s' '{"query":"led_strip","target":"esp32s3"}' | node scripts/run-tool.mjs resolve_component --stdin

Runtime notes

• manage_env can succeed even when ESP-IDF is not installed, because reporting NOT_FOUND is a valid diagnostic result.
• manage_env({ action: "install" }) returns manual install guidance; it does not clone repositories or run upstream install scripts inside the skill bundle.
• resolve_component uses the official ESP Component Registry over the network and should be treated as an explicit online lookup step.
• decode_panic needs the matching ELF file and a working addr2line binary from the ESP-IDF toolchain.
• analyze_monitor is still log-driven; it does not open serial ports by itself in this MVP.
• flash_and_monitor does execute idf.py flash monitor, so the serial port, permissions, and toolchain environment must already be working.
• safe_build depends on a shell environment where idf.py is executable.
• The current hardware rules cover esp32, esp32s3, esp32c3, esp32c6, esp32c5, esp32h2, and esp32p4.
• Common SKU names are normalized to family rules, for example ESP32-C6FH4 -> esp32c6 and ESP32-S3-PICO-1-N8R2 -> esp32s3.
• Audit results can include file, line, and evidence fields so the host can point back to the exact source location.
• The pin audit can resolve several common patterns beyond direct literals, including pin_bit_mask, common ..._io_num fields, macro chains, simple assignment aliases, and #define / const gpio_num_t aliases.
• Pass user-controlled text through stdin JSON, not shell interpolation.

Files

• scripts/run-tool.mjs — minimal stdin-driven tool runner for ClawHub-safe execution
• dist/index.js — bundled runtime entry
• dist/data/soc/*.json — current SoC rules database (esp32, esp32s3, esp32c3, esp32c6, esp32c5, esp32h2, esp32p4)

Out of scope for this MVP bundle

The following ideas are roadmap items, not current bundle guarantees:

• automatic idf_component.yml maintenance
• automatic partitions.csv edits
• deep serial-port management UX
• HIL automation with pytest-embedded