Skip to content
Get packs

Guide · Agent skill

How to use the M5Stack Device Onboarding agent skill (m5-onboard)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The m5-onboard skill is an agent skill for Claude that walks you through setting up a freshly connected M5Stack ESP32 device: it finds the board on USB, identifies the model, flashes UIFlow 2.0 firmware, and copies a MicroPython app bundle onto the device. This guide explains what an agent skill is, how to install m5-onboard, how to ask for it in plain language, and what it needs from your computer. By the end you will know how to run it safely on a Cardputer, Core or similar board.

M5Stack Device Onboardinganthropics/claude-plugins-official · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the m5-onboard ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills instead.
  2. 2Clone the build-with-claude repo. Make a local clone of https://github.com/moremas/build-with-claude, which contains the onboard scripts and the buddy/ app bundle. The skill notes that /maker-setup creates this clone.
  3. 3Connect the board by USB. Plug in your M5Stack ESP32 device and make sure only the board you want to provision is connected.
  4. 4Ask for the onboarding. Tell Claude something like "I just plugged in my Cardputer, set it up". State the model if it is not a Cardputer-Adv, since the default variant is cardputer-adv.
  5. 5Press G0 and RST when prompted. When the agent asks, hold G0, press and release RST, keep holding G0 about one more second, then release it. Wait for the screen to go dark.
  6. 6Wait for the flash and app install. Let the run finish. The skill notes the full run takes about 2–3 minutes and that the device reboots between stages.
  7. 7Verify the device. If something seems wrong afterwards, ask for a smoke test, which checks I2C, LCD, speaker and button.

What an agent skill is and what m5-onboard does

An agent skill is a folder containing a SKILL.md file and any supporting files. When a skill is installed, the agent reads its description and loads its instructions when your request matches the situation described there.

m5-onboard covers the full cold-start workflow for an M5Stack ESP32 device (Cardputer, Cardputer-Adv, Core, CoreS3, Stick). The agent detects the device on USB, identifies the model, flashes UIFlow 2.0 firmware, and pushes a MicroPython app bundle to /flash/ so the device boots into user software. The shipped apps are Claude Buddy, Snake and Hello, which talk over BLE or USB.

  • Detect the device on USB and confirm the chip with esptool.
  • Flash UIFlow 2.0 firmware.
  • Install the buddy app bundle (Claude Buddy, Snake, Hello).
  • Run a smoke test (I2C, LCD, speaker, button) when a flashed device seems broken.

Install the m5-onboard skill

Download the m5-onboard ZIP from this page and unzip it. Then choose one of two locations. For a personal install available in every project, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead of Claude Code, upload the ZIP under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills → upload the ZIP

Set up the scripts and app bundle before the first run

The executable scripts and the buddy/ app bundle are not inside the skill folder. They live in a local clone of https://github.com/moremas/build-with-claude. The skill says the /maker-setup command creates this clone. Run every script from inside that clone's onboard/ directory so that --apps buddy finds the buddy/device/ payload.

Python 3 must be installed, and the computer needs serial access to the USB port.

  • Requirement: Python 3
  • Requirement: a local clone of https://github.com/moremas/build-with-claude
  • Requirement: a physical M5Stack ESP32 device connected by USB

Trigger the skill with natural requests

You do not need to name the script. Plug the board in and say what you want in plain words. The skill's description triggers on requests to plug in, flash, provision or reset an M5Stack or ESP32 board, and on the phrase "m5-onboard go".

If several devices are connected, the agent should ask which port to use rather than guess. If you say "another Buddy" or "same as last time", it defaults to the buddy bundle.

  • "I just plugged in my Cardputer, set it up."
  • "Flash and provision this M5Stack board."
  • "Refresh the apps on my Core, don't reflash it."
  • "Run a smoke test on the device, something feels broken."
  • "m5-onboard go"

Press the physical buttons when asked

Flashing on native-USB boards needs a button press on the device, and there is no software path around it. When the agent reaches the flash stage, it will tell you to hold G0 on the back of the Cardputer, briefly press and release RST while still holding G0, keep holding G0 for about one more second, then release it. The screen should go fully dark, which means download mode is active.

If the device boots into UIFlow instead of going dark, G0 was released too early; try again holding it longer. The agent is designed to wait for your confirmation before continuing.

  • Hold G0, press and release RST, keep G0 held about one more second, then release.
  • Dark screen = download mode active.
  • Reboot into UIFlow = release came too early; retry.

Safety: scripts, firmware and wrong variants

This skill runs Python scripts on your machine and flashes firmware onto your device. Only use it if you are comfortable with that. The skill does not declare network use, but it does say fetch_firmware.py queries the M5Burner manifest API and downloads the UIFlow 2.0 binary into the system temp directory.

Choose the variant carefully. The skill defaults to --variant cardputer-adv. A Cardputer and a Cardputer-Adv share a form factor but take different firmware images, and flashing the wrong one can boot-loop the device. If you say "Cardputer" without "Adv", the agent should ask. Do not plug in a different board while flashing is in progress.

  • Scripts run on your machine: Python files in scripts/ are executed.
  • Firmware is flashed to the device with esptool.
  • Wrong variant can boot-loop the device; state the model clearly.
  • Only one device should be targeted at a time.

What people use it for

  • Provision a newly bought Cardputer-Adv with the Claude Buddy app bundle.
  • Set up several identical devices with the same buddy bundle for a repeatable routine.
  • Refresh or replace apps on an already-flashed Core board without reflashing firmware.
  • Run a smoke test on a board that seems to have a hardware fault.
  • Check what the device can do after a reset.

Frequently asked questions

Is the m5-onboard skill free?

The skill is published under the Apache-2.0 licence, as listed on this page. The source does not mention pricing, and you still need your own M5Stack hardware.

What do I need to run m5-onboard?

You need Python 3, serial access to the USB port, a local clone of https://github.com/moremas/build-with-claude containing the onboard scripts and buddy/ bundle, and a physical M5Stack ESP32 device connected by USB.

Where do I put the m5-onboard skill?

Unzip it into ~/.claude/skills/ for all projects or into a project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

Why does the device not go into download mode?

On native-USB boards the flash stage needs manual button presses. Hold G0, press and release RST while holding G0, keep G0 held about one more second, then release. If the device boots into UIFlow, G0 was released too early.

Which M5Stack models does it support?

The description names Cardputer, Cardputer-Adv, Core, CoreS3 and Stick. The default target is cardputer-adv, so name the model if it is a different board.

Does m5-onboard use the internet?

The skill's metadata says it does not use the network, but its instructions say fetch_firmware.py downloads the UIFlow 2.0 binary from the M5Burner manifest API. Check that before you run it on a restricted network.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use m5-onboard if you have a physical M5Stack or ESP32 board and want a guided, repeatable setup that installs UIFlow 2.0 and the buddy app bundle. Pick something else if you do not have the hardware, do not want scripts run and firmware flashed on your computer, or may plug in a different board while the wrong variant is targeted.

Download the skill