build-platformio

Original：🇨🇳 Chinese

Translated

1 scriptsChecked / no sensitive code detected

This is used when you need to compile embedded projects via the PlatformIO command line, call the built-in script to parse environment configurations, execute builds, and locate firmware artifacts.

3installs

Sourceleokemp223/embed-ai-tool

Added on2026-05-16

NPX Install

npx skill4agent add leokemp223/embed-ai-tool build-platformio

SKILL.md Content (Chinese)

View Translation Comparison →

Building PlatformIO Projects

Applicable Scenarios

The

Project Profile

specifies

build_system: platformio

or a

platformio.ini

exists in the workspace.

Users want to compile, clean, or upload firmware for a PlatformIO project.
A new
```
ELF
```
,
```
HEX
```
, or
```
BIN
```
is required for flashing or debugging processes.
Need to confirm if PlatformIO CLI is ready before building.

Required Inputs

Workspace path (containing
```
platformio.ini
```
), or an existing
```
Project Profile
```
.
Optional environment name.

Automatic Detection

The script automatically detects if the
```
pio
```
command is available and retrieves its version.
Parses the list of environments in
```
platformio.ini
```
, extracting platform, board, framework, and upload protocol.
Identifies
```
default_envs
```
in the
```
[platformio]
```
section as the default environment.
If no environment is specified and a default environment exists, use the default environment; otherwise, use the first environment.
Searches for firmware.elf/hex/bin artifacts in
```
.pio/build/<env>/
```
, sorted by
```
ELF > HEX > BIN
```
.
If multiple equally reasonable environments exist, list candidates instead of making silent guesses.

Execution Steps

First read references/usage.md to confirm whether this is environment detection, listing environments, executing builds, or just scanning artifacts.
If unsure whether the environment is ready, first run the
```
--detect
```
mode of the built-in script scripts/platformio_builder.py to confirm.
Use
```
--list-envs --project-dir <dir>
```
to confirm available environments, then use
```
--project-dir
```
+
```
--env
```
to execute the build.
Read the build results and artifact scan report output by the script, focusing on the preferred artifacts (ELF > HEX > BIN) and failure categories.
Write the build environment, artifact path, and board information back to the
```
Project Profile
```
, and hand it over to downstream skills when needed.

Failure Handling

When the
```
pio
```
command is unavailable, return
```
environment-missing
```
.
When
```
platformio.ini
```
does not exist or the environment name is invalid, return
```
project-config-error
```
.
When the build appears successful but no flashable or debuggable artifacts are found, return
```
artifact-missing
```
.
When multiple equally reasonable environments exist and arbitrary selection is unsafe, return
```
ambiguous-context
```
.

Platform Notes

PlatformIO is fully cross-platform (Linux / macOS / Windows) with no platform restrictions.
The built-in script uses Python standard libraries and subprocess to call
```
pio
```
, and the build scheduling path itself is cross-platform.
The build directory and artifact paths in the output should remain absolute paths for direct reuse by downstream flashing and debugging skills.

Output Conventions

Output the build command, project directory, environment name, board, and preferred artifact path.

Update the

Project Profile

with

artifact_path

,

artifact_kind

, and board information.

Recommend
```
flash-openocd
```
or
```
debug-gdb-openocd
```
after success.

Handover Relationships

When the next step is to flash the program to hardware, hand over the successful build result to
```
flash-openocd
```
.
When the next step requires symbol information or a debugging session, hand over the successful build result to
```
debug-gdb-openocd
```
.
PlatformIO has a built-in upload function (
```
--upload
```
), which can be used directly in simple scenarios without handover.