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:

• - INLINECODE0
• INLINECODE1
• INLINECODE2
• INLINECODE3
• INLINECODE4
• INLINECODE5
• INLINECODE6
• INLINECODE7
• INLINECODE8

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

• - 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:

CODEBLOCK0

explore_demo

• - inspect local INLINECODE15
• find matching demos by keyword
• read the best matching README.md / INLINECODE17
• summarize hardware requirements and structure

Example invocation:

CODEBLOCK1

safe_build

• - 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:

CODEBLOCK2

analyze_partitions

• - 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 INLINECODE24

Example invocation:

CODEBLOCK3

decode_panic

• - 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:

CODEBLOCK4

analyze_monitor

• - 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:

CODEBLOCK5

flash_and_monitor

• - run INLINECODE30
• 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:

CODEBLOCK6

execute_project

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

Example invocation:

CODEBLOCK7

resolve_component

• - 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:

CODEBLOCK8

Runtime notes

• - manage_env can succeed even when ESP-IDF is not installed, because reporting NOT_FOUND is a valid diagnostic result.
• INLINECODE38 returns manual install guidance; it does not clone repositories or run upstream install scripts inside the skill bundle.
• INLINECODE39 uses the official ESP Component Registry over the network and should be treated as an explicit online lookup step.
• INLINECODE40 needs the matching ELF file and a working addr2line binary from the ESP-IDF toolchain.
• INLINECODE42 is still log-driven; it does not open serial ports by itself in this MVP.
• INLINECODE43 does execute idf.py flash monitor, so the serial port, permissions, and toolchain environment must already be working.
• INLINECODE45 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
• INLINECODE64 — bundled runtime entry
• INLINECODE65 — 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 INLINECODE75