build-platformio

Build a PlatformIO project

Applicable scenarios

Project Profile is indicated in build_system: platformio or exists in the workspace platformio.ini。
The user wants to compile, clean, or upload firmware for a PlatformIO project.
The flashing or debugging workflow requires a new ELF、HEX or BIN。
It is necessary to confirm whether the PlatformIO CLI is ready before building.

As soon as the script starts, it automatically reuses the last successful profile in the project root directory .em_skill.json as the default parameters (explicit parameters take precedence; there is no need to manually pass --resume）；--resume is only used to assert that the cache must exist; if there is no cache, it exits with a non-zero status. When there is no cache or the user explicitly requests re-detection, the script automatically falls back to a normal scan.
The script automatically detects whether the pio command is available and obtains the version.
Parse the environment list in platformio.ini , extracting platform, board, framework, and upload protocol.
Identify [platformio] in the default_envs section as the default environment.
If no environment is specified and a default environment exists, use the default environment; otherwise use the first environment.
In .pio/build/<env>/ , search for firmware.elf/hex/bin artifacts, sorted by ELF > HEX > BIN .
If multiple equally reasonable environments exist, list the candidates instead of silently guessing.

First read references/usage.md, and confirm whether this time is environment detection, listing environments, executing a build, or only scanning artifacts.
If unsure whether the environment is ready, first run the bundled script scripts/platformio_builder.py 's --detect mode to confirm.
Use --list-envs --project-dir <dir> to confirm the 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 artifact (ELF > HEX > BIN) and failure classification.
Write the build environment, artifact paths, and board information back to Project Profile, and hand off to downstream skills when needed.

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 artifact is found, return artifact-missing。
When multiple equally reasonable environments exist and choosing any one is unsafe, return ambiguous-context。

PlatformIO is fully cross-platform (Linux / macOS / Windows), with no platform restrictions.
The bundled script uses the Python standard library and subprocess to invoke pio; the build scheduling path itself is cross-platform.
The build directory and artifact paths in the output should remain absolute paths, so that downstream flashing and debugging skills can reuse them directly.

Output the build command, project directory, environment name, board, and preferred artifact path.
Use artifact_path、artifact_kind and board information to update Project Profile。
After success, recommend flash-openocd or debug-gdb-openocd。

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