M5Stack 一键上手
为 M5Stack ESP32 自动检测设备、刷入 UIFlow 固件并安装 MicroPython 应用。
文档说明了设备识别、刷写、人工按钮确认、日志监控、缓存权限和恢复路径，也披露了 WiFi、BLE、USB 及外部下载的数据流；但默认流程会刷写设备并安装外部依赖，且可自动引导系统级 Python 安装，未充分说明最小权限、敏感凭据处理和刷写前确认，因此扣分。
文档对多系统、端口、波特率、重试、异常刷写和手动复位有较具体说明；但可执行脚本、测试套件和关键路径复现证据未提供，且关于 boot.py 备份的描述存在不一致，因此静态评估限制在中低分。
目标用户、设备型号、部分运行与非适用场景、人工按钮触发条件和多操作系统差异较清楚；但默认型号依赖经验判断，中文支持未说明，核心依赖外部 GitHub、M5Burner、pip 及 Claude Desktop，面向中国大陆网络的可达性和替代路径不足，因此扣分。
文档结构较完整，包含触发条件、决策树、阶段说明、平台注意事项、依赖和回滚方式；仓库提供 Apache-2.0 许可及官方来源信息，但技能自身缺少版本、变更记录、明确维护责任、安装包固定版本和系统化故障 FAQ，因此未满分。
目标是完成 M5Stack 检测、固件刷写和应用安装，命令、阶段和预期设备体验均有描述，理论上能直接支持核心任务；但脚本和设备结果未在材料中验证，外部应用包和网络依赖增加失败及后续人工处理成本，因此限制在静态上限以内并扣分。
技能提供了命令、路径、日志关键词、硬件签名和若干具体故障模式，具备一定审计性；但没有提交的测试套件、CI 覆盖、第三方执行记录或独立复现结果，仓库 CI 也未证明该技能关键路径，因此只能给有限分。
- 默认流程涉及固件刷写和文件安装，用户应在执行前明确确认目标端口、型号及可接受的设备状态变化。
- 应用包来自外部本地克隆，固件和 esptool 通过外部服务或 pip 获取；应验证来源、版本、哈希和网络可达性。
- 文档提到事件 WiFi 凭据写入应用包，使用前应检查并移除或替换硬编码配置。
- boot.py 备份说明与后文描述不一致，不能仅凭文档假定回滚一定完整。
它能做什么 & 适用场景
m5-onboard 面向刚接入或需要重置的 M5Stack ESP32 设备，覆盖 Cardputer、Cardputer-Adv、Core、CoreS3 和 Stick 等型号。它检测 USB 端口、识别硬件、获取并刷入 UIFlow 2.0 固件，然后把 Claude Buddy 等 MicroPython 应用写入设备。默认目标是 Cardputer-Adv，并支持 macOS、Linux 和 Windows。刷写原生 USB ESP32-S3 设备时仍需要用户手动操作 G0 和 RST 按钮。
运行 onboard.py 完成 USB/串口检测、芯片探测、硬件型号判断、从 M5Burner manifest API 下载固件、使用 esptool 刷写固件，并通过 paste-mode REPL 将 buddy/device 中的 Python 文件上传到 /flash/。安装带有根目录 main.py 的应用包时，还会设置 UIFlow 的 boot_option=2。可选的 install_apps.py 用于仅刷新应用，smoke_test.py 用于检查 I2C、LCD、扬声器和按键。
- 用户首次接入 Cardputer-Adv，希望自动完成固件和 Claude Buddy 应用配置。
- 用户已有 UIFlow 固件，只想重新上传或刷新 MicroPython 应用。
- 用户怀疑设备异常，需要运行 I2C、屏幕、扬声器和按键检查。
- 用户要为 Core、CoreS3、Basic、Fire 或其他支持型号指定对应固件变体。
- 用户需要在 macOS、Linux 或 Windows 上重复执行可恢复的设备 provisioning 流程。
优缺点一览
- 覆盖检测、识别、刷写和应用安装的完整冷启动流程。
- 支持 Cardputer-Adv、Cardputer、Core、CoreS3、Stick 等多种 M5Stack/ESP32 设备。
- 支持 macOS、Linux 和 Windows。
- 内置 pyserial，并可在首次运行时提示安装 esptool。
- 处理了原生 USB、NVS boot_option、REPL paste mode 和刷写重试等常见问题。
- 需要真实的 M5Stack/ESP32 硬件和 USB 串口访问权限。
- 原生 USB ESP32-S3 刷写不能完全自动化，必须手动按键进入下载模式。
- 需要访问网络下载 UIFlow 固件，并可能安装 esptool。
- 技能的可执行脚本和 buddy 应用包不在该 SKILL.md 所在目录，而是在 build-with-claude 克隆的 onboard/ 中。
- 源材料未提供独立测试套件或各平台验证矩阵的证据。
如何安装
该技能属于 anthropics/claude-plugins-official 仓库中的 cwc-makers 插件。README 说明可在 Claude Code 中通过插件系统安装集合，例如运行 /plugin install cwc-makers@claude-plugins-official；随后使用 /maker-setup 创建 build-with-claude 本地克隆，因为可执行脚本和 buddy 应用包位于该克隆的 onboard/ 目录。首次运行前必须有 Python；esptool 缺失时，脚本会提示安装。
如何使用
将 M5Stack 接入 USB 后，在 onboard/ 目录运行 python3 scripts/onboard.py --apps buddy。原生 USB 设备的刷写需要在日志提示时按住设备背面的 G0，短按并释放 RST，继续按住 G0 约一秒后释放，直到屏幕变黑；确认后再继续。只安装应用可运行 python3 scripts/install_apps.py --port <PORT> --src buddy，检查硬件可运行 python3 scripts/smoke_test.py。