Claw ESP Expert

ESP-IDF 专家型技能：环境检查、examples 导航、GPIO 规则审计与构建诊断。

Security Scan

The skill's code, declared requirements, and runtime instructions align with an ESP‑IDF diagnostic tool: it inspects project files, runs idf.py/addr2line locally, and performs local static analysis; nothing requests unrelated credentials or performs unexplained network/exfiltration behavior.

Purpose & Capability

Name/description (ESP‑IDF expert) match what the bundle implements: Node.js code that inspects projects, audits GPIO/pin usage, analyzes partition tables, decodes panic traces and drives builds via idf.py. Required binaries (node, idf.py) are appropriate and proportional; no unrelated credentials or config paths are requested.

Instruction Scope

SKILL.md and the code consistently limit actions to the ESP‑IDF project scope: reading projectPath, sdkconfig, partitions.csv, source files, ELF files, and invoking idf.py/addr2line. The SKILL.md explicitly warns not to scan arbitrary user configs. One expected network action is 'resolve_component' which performs lookups against the official ESP Component Registry; otherwise runtime behavior is local. Users should note the skill will read files under provided project paths and execute local toolchain commands.

Install Mechanism

No install spec — the shipped bundle contains compiled JS (dist/) and a run-tool script and runs under node. There are no download-from-URL installs or external extract steps in the manifest, so nothing is pulled from arbitrary servers during installation.

Credentials

The bundle requires no secret env vars. At runtime it reads standard environment values (PATH, HOME/USERPROFILE, IDF_PATH, PATHEXT) to detect tool availability and common install locations — which is reasonable for environment checks. It will invoke local binaries (idf.py, addr2line) as needed; no broad credential access is requested.

Persistence & Privilege

always is false and the skill does not request system‑wide persistence. The code returns patch suggestions/updated manifests rather than silently modifying project files by default. There is no evidence it changes other skills' configs or stores credentials.

Assessment

This bundle appears coherent for ESP‑IDF diagnostics, but before installing consider: (1) it will read files under any project path you provide (sdkconfig, partitions.csv, source and ELF files) and will spawn local tools (idf.py, addr2line, child processes) — run it only on projects you trust; (2) resolve_component performs an explicit online lookup to the official Component Registry (network access); (3) review scripts/run-tool.mjs if you want to confirm exact command invocations; (4) if you are concerned about builds or flashing, run the tool in an isolated/dev machine or container so it cannot touch production hardware or sensitive local data.

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