docs: Add podman-vscode-build skill (project-chip#72579)

* docs: Add podman-vscode-build skill

Change-Id: Id8bc6d6cdb5d022f71615dc9b180808dc28c59e9

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: soares-sergio

.agents/skills.md

@@ -19,6 +19,15 @@ etc.) to assist with development and code review in the Matter repository.
     Pull Request descriptions.
 -   **Triggers**: Use when preparing or writing descriptions for pull requests.
 
+### Podman VSCode Build
+
+-   **Location**: `.agents/skills/podman-vscode-build/`
+-   **Purpose**: Guidelines for building and testing Matter examples using
+    Podman with the official vscode build image in a non-interactive
+    environment.
+-   **Triggers**: Use when running builds or tests inside a Podman container,
+    especially when targeting embedded or cross-compiled platforms.
+
 ## Using Skills
 
 AI agents will automatically discover and load these skills when they are

.agents/skills/podman-vscode-build/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: podman-vscode-build
+description:
+    Guidelines for building Matter examples and running tests using Podman with
+    the vscode image in a non-interactive environment.
+---
+
+# Building and Testing Matter with Podman (VSCode Build Image)
+
+This skill provides guidelines and instructions for configuring, launching, and
+executing build/test commands within a Podman container using the official
+`ghcr.io/project-chip/chip-build-vscode` image.
+
+Podman runs rootless, which avoids file ownership complications (where files
+generated in the container are owned by root on the host) commonly encountered
+with Docker.
+
+---
+
+## 1. Prerequisites & Host Configuration
+
+Before launching Podman, you must configure storage to avoid namespace and user
+limit errors (e.g., insufficient UIDs or GIDs in the user namespace).
+
+### Edit storage.conf
+
+Edit or create `$HOME/.config/containers/storage.conf` to include:
+
+```toml
+[storage]
+driver = "overlay"
+
+[storage.options]
+ignore_chown_errors = "true"
+```
+
+### System Reset & Verification
+
+If you previously attempted to use Podman without this setting, you may need to
+reset the storage.
+
+> [!CAUTION] Running `podman system reset` will delete all existing Podman
+> containers, images, and volumes.
+
+1. Reset Podman:
+    ```bash
+    podman system reset
+    ```
+2. Verify that `graphDriverName` is `overlay` (instead of `vfs`):
+    ```bash
+    podman info | grep graphDriverName
+    ```
+
+---
+
+## 2. Locating the VSCode Image Tag
+
+The correct tag for `ghcr.io/project-chip/chip-build-vscode` changes as
+dependencies are updated. To find the tag currently used in CI:
+
+-   Inspect the workflow files under `.github/workflows/` (such as `tests.yaml`
+    or `build.yaml`) or the cloudbuild configurations under
+    `integrations/cloudbuild/` (such as `chef.yaml`).
+-   Search for the image reference
+    `ghcr.io/project-chip/chip-build-vscode:<TAG>` to identify the correct
+    version tag (e.g., `200`).
+
+---
+
+## 3. Starting the Container
+
+To start a persistent vscode container in the background:
+
+```bash
+podman run -dt --cap-add=SYS_PTRACE --name bld_vscode \
+    --volume /path/to/connectedhomeip:/workspace \
+    ghcr.io/project-chip/chip-build-vscode:<TAG> \
+    /bin/sh
+```
+
+_Replace `/path/to/connectedhomeip` with the absolute path to your local
+repository checkout, and `<TAG>` with the version tag found in step 2._
+
+---
+
+## 4. Non-Interactive Command Execution
+
+Since agents run in a non-interactive environment, do **NOT** use interactive
+flags like `-it` (e.g. `podman exec -it ...`). Instead, execute commands
+directly or script them.
+
+### Activation is Mandatory
+
+Because `podman exec` does not load login shell initialization scripts, the
+Pigweed build environment is **not activated by default**. Sourcing the
+environment activation script is required prior to compiling.
+
+-   **Bootstrap**: Use `scripts/bootstrap.sh` if this is the first time setup
+    inside the container, or if packages or submodules have changed.
+-   **Activate**: Use `scripts/activate.sh` for subsequent runs.
+
+Run the commands in a single subshell using `bash -c`:
+
+```bash
+podman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target <target> build"
+```
+
+### Sourcing Bootstrap for Specific Platforms
+
+By default, running `bootstrap.sh` inside the container installs python
+requirements for host and Zephyr builds. To enable building for other specific
+embedded platforms (which downloads/configures additional pip dependencies),
+pass the platform names to the `-p` parameter:
+
+```bash
+podman exec -w /workspace bld_vscode bash -c "source scripts/bootstrap.sh -p esp32,nrfconnect,silabs,telink"
+```
+
+Supported platform identifiers include: `esp32`, `nrfconnect`, `silabs`,
+`telink`, `bouffalolab`, `mbed`, `ti`, `zephyr`.
+
+### Additional ESP32 Setup
+
+If building for the ESP32 platform, the ESP-IDF toolchain Python requirements
+inside the container must also be explicitly set up. Run the following command
+inside the container after bootstrapping:
+
+```bash
+podman exec -w /workspace bld_vscode bash -c "/opt/espressif/esp-idf/install.sh"
+```
+
+### Additional Nordic nRF Connect Setup
+
+If compiling for Nordic nRF Connect targets, the pre-installed SDK files must be
+synchronized and updated before building. Discard local template modifications
+first, then run the update script inside the container:
+
+```bash
+podman exec -w /workspace bld_vscode git -C /opt/NordicSemiconductor/nrfconnect/zephyr checkout -- zephyr-env.sh
+podman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && python3 scripts/setup/nrfconnect/update_ncs.py --update --shallow"
+```
+
+---
+
+## 5. Platform Build Examples & Output Directories
+
+Using Podman with the official vscode image is particularly valuable when
+compiling for embedded or cross-compiled targets, as the image pre-packages all
+required toolchains and compilers.
+
+Here are examples of compiling Matter applications (e.g., `all-devices-app` or
+`all-clusters-app`) for various platforms and where the executables/artifacts
+are generated:
+
+### A. Linux ARM64 (e.g. Raspberry Pi)
+
+-   **Target**: `linux-arm64-all-devices-boringssl-no-ble-clang`
+-   **Build Command**:
+    ```bash
+    podman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target linux-arm64-all-devices-boringssl-no-ble-clang build"
+    ```
+-   **Output Artifact**:
+    `<checkout_root>/out/linux-arm64-all-devices-boringssl-no-ble-clang/all-devices-app`
+
+### B. ESP32 (devkitc)
+
+-   **Target**: `esp32-devkitc-all-devices`
+-   **Build Command**:
+    ```bash
+    podman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target esp32-devkitc-all-devices build"
+    ```
+-   **Output Artifacts**:
+    `<checkout_root>/out/esp32-devkitc-all-devices/all-devices-app.elf` and
+    `all-devices-app.bin`
+
+### C. Silicon Labs EFR32 (brd4187c)
+
+-   **Target**: `efr32-brd4187c-all-devices`
+-   **Build Command**:
+    ```bash
+    podman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target efr32-brd4187c-all-devices build"
+    ```
+-   **Output Artifacts**:
+    `<checkout_root>/out/efr32-brd4187c-all-devices/matter-silabs-all-devices-example.out`
+    (and `.hex` / `.s37`)
+
+### D. Nordic nRF Connect (nrf52840dk)
+
+_Note: Building with the Zephyr SDK toolchain requires setting
+`ZEPHYR_TOOLCHAIN_VARIANT=zephyr` explicitly._
+
+-   **Target**: `nrf-nrf52840dk-all-clusters`
+-   **Build Command**:
+    ```bash
+    podman exec -w /workspace bld_vscode bash -c "export ZEPHYR_TOOLCHAIN_VARIANT=zephyr && source scripts/activate.sh && ./scripts/build/build_examples.py --target nrf-nrf52840dk-all-clusters build"
+    ```
+-   **Output Artifacts**:
+    `<checkout_root>/out/nrf-nrf52840dk-all-clusters/merged.hex` (contains both
+    bootloader and app) and `zephyr/zephyr.elf`
+
+### E. Telink (tlsr9518adk80d)
+
+-   **Target**: `telink-tlsr9518adk80d-all-devices`
+-   **Build Command**:
+    ```bash
+    podman exec -w /workspace bld_vscode bash -c "source scripts/activate.sh && ./scripts/build/build_examples.py --target telink-tlsr9518adk80d-all-devices build"
+    ```
+-   **Output Artifacts**:
+    `<checkout_root>/out/telink-tlsr9518adk80d-all-devices/zephyr/zephyr.bin`
+
+---
+
+## 6. Accessing Build Artifacts
+
+Because the repository root is mounted as a volume
+(`--volume /path/to/connectedhomeip:/workspace`), any build outputs written to
+`/workspace/out/` inside the container are **immediately accessible** on the
+host filesystem at `<checkout_root>/out/`.
+
+There is **no need** to copy binaries using `podman cp`. You can access or run
+the built binary directly from your host repository checkout:
+
+```bash
+cp out/<target>/<binary_name> /path/to/destination
+```