Skip to main content
skill CX Codex

ota-deployment-guardian — Claude Code skill: setup and features

ota-deployment-guardian prevents remote bricking on ESP32 boards and Arduino Uno R4 WiFi during OTA updates. Troubleshoots disappearing network ports and sets up rollback workflows.

MIT 115 installs ★ 33 updated 2026-10-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wedsamuel1230/embedded-engineering-skills --skill ota-deployment-guardian -a claude-code
Open on GitHub

What ota-deployment-guardian does

This skill guides over-the-air firmware deployments for ESP32, Nano ESP32, and Arduino Uno R4 WiFi boards. It isolates IP reachability from mDNS discovery failures. Ping success does not prove upload capability.

The workflow forces users to keep the OTA loop active across sketch versions. For native ESP-IDF setups, it inspects partition slots and rollback-safe NVS schemas. Uno R4 WiFi boards follow specific rules because their Wi-Fi module behaves differently from generic ESP32 hardware.

Rollout safety demands a confirmed fallback route before remote flashing begins. Recent core updates must also be checked whenever OTA stops working unexpectedly. Board-level procedures here do not confirm cryptographic image signing or secure boot.

What it helps with

  • keep OTA handlers active across subsequent firmware sketches
  • troubleshoot disappearing network ports when ping still responds
  • plan rollback strategies for remote microcontroller rollouts
  • verify native ESP-IDF app slots and boot confirmation routines

Example prompts for the agent

  • My ESP32 responds to ping, but the network port disappeared in Arduino IDE. How do I fix this?
  • Review this Uno R4 WiFi sketch to ensure it will still accept OTA uploads after the update
  • Help me design an ESP-IDF rollback and NVS layout for a field-deployed sensor

How to install ota-deployment-guardian

1Skills CLI (Vercel)

npx skills add wedsamuel1230/embedded-engineering-skills --skill ota-deployment-guardian -a claude-code

2Manually: put the files in place

~/.claude/skills/ota-deployment-guardian/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ota-deployment-guardian/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ota-deployment-guardian

How do I install ota-deployment-guardian in Claude Code?

Run npx skills add wedsamuel1230/embedded-engineering-skills --skill ota-deployment-guardian -a claude-code in your terminal. This configures the skill at ~/.claude/skills/ota-deployment-guardian/SKILL.md.

What does ota-deployment-guardian do?

It provides safety workflows for over-the-air updates on ESP32 and Uno R4 WiFi devices. It prevents losing remote access by enforcing rollback paths and validating sketch OTA handlers.

Why does the skill treat Uno R4 WiFi differently from ESP32?

The Uno R4 WiFi runs its networking stack through a companion module with specific firmware caveats. It does not share the same operational architecture as a direct ESP32 board.

Source text

SKILL.md · MIT
---
name: ota-deployment-guardian
description: Use when users need safe over-the-air update workflows for ESP32-class boards or Arduino Uno R4 WiFi, including OTA sketch requirements, network port discovery failures, remote recovery planning, and rollout safety checks.
metadata: {triggers: "OTA, over-the-air update, rollback, remote recovery, deployment"}
---

# OTA Deployment Guardian

Use this skill when a device is updated remotely and losing the update path
would be expensive.

## Resources

- `references/ota-safe-sketch.md` - minimum sketch-side OTA contract and guardrails
- `references/discovery-and-network-ports.md` - IDE, mDNS, IP reachability, and disappearing network port triage
- `references/recovery-and-rollback.md` - rollout safety, rollback, and last-resort recovery planning
- `references/native-espidf-rollback.md` - native app slots, boot acceptance, stopped-output acknowledgement and rollback-compatible NVS/calibration schemas
- `../../docs/board-support/uno-r4-family.md` - Uno R4 Minima and Uno R4 WiFi board-family caveats

## When to Use

Use this skill when the request involves:

- OTA uploads for ESP32, Nano ESP32, or Uno R4 WiFi
- network port appears briefly or disappears
- IDE can ping the device but cannot upload
- keeping a remote weather station or deployed board updateable
- avoiding self-bricking after an OTA deployment

Do not use this skill for ordinary bench USB uploads unless the user is clearly
preparing for later OTA deployment.

## Workflow

1. Confirm the board family:
   - Native ESP-IDF -> open `references/native-espidf-rollback.md`; build intake
     stays with `embedded-build-workflow`, not Arduino sketch instructions.
   - ESP32 or Nano ESP32 -> open `references/ota-safe-sketch.md`
   - Uno R4 WiFi -> also open `../../docs/board-support/uno-r4-family.md`
2. Separate discovery failures from sketch failures:
   - ping works but network port disappears -> open
     `references/discovery-and-network-ports.md`
   - OTA works once, then disappears after the new sketch runs -> verify the new
     sketch still implements the OTA path in `ota-safe-sketch.md`
3. Before suggesting a rollout, check `references/recovery-and-rollback.md` for
   recovery path, rollback strategy, and what must stay available over USB.
4. Treat core-version changes as a possible variable when OTA previously worked
   and later became unreliable.

## Security And Maintenance Boundary

Use the router's connected-device security reference for secrets, signed images,
dependency versions, staged rollout, rollback, vulnerability response, and
decommissioning. This skill's board-specific OTA procedures do not prove that
the device has secure boot, authenticated updates, or a recoverable field
deployment; verify those controls on the exact target.

## Core Rules

- Never assume OTA remains available after a new sketch unless the sketch keeps
  the OTA path alive.
- Distinguish reachability from OTA discovery. Ping success does not prove the
  IDE can discover or upload.
- Keep at least one recovery path in reserve for high-cost remote devices.
- For Uno R4 WiFi, keep board-family caveats explicit. Its WiFi side is not the
  same operational model as a plain ESP32 board.

## Verification

- Confirm the sketch still connects to the intended network and services the OTA
  path after boot.
- Confirm whether the failure is discovery-only, upload-only, or full device
  reachability loss.
- For remote deployments, confirm the rollback or physical recovery plan before
  recommending an update.
- If board or core versions changed recently, capture the exact versions before
  concluding the failure is in user code.

## Integration

- Pair with `arduino-cli-skill` when the user needs command-line upload or port
  inspection.
- Pair with `field-power-and-connectivity-triager` when the OTA path fails only
  off USB or in field power conditions.
- Pair with `error-message-explainer` when the OTA sketch itself does not build.

## Shared Output Contract

Use [the shared Arduino skill contract](../../docs/arduino-skill-contract.md):
state assumptions, required tools and versions, implementation steps,
tests/evidence by proof stage, known limitations, and recovery/security notes.

© wedsamuel1230 · MIT · wedsamuel1230/embedded-engineering-skills

Similar skills

All skills for DevOps and infrastructure →

From the same set19

The whole set →
code-review-facilitator The code-review-facilitator skill reviews Arduino, ESP32, and RP2040 projects for memory risks, structural issues, and common mistakes. Use it before publishing code or after finishing a feature. CX Codex +1 154installs readme-generator readme-generator generates README.md files for Arduino, ESP32, and RP2040 projects. Use it when a working project needs clear GitHub documentation. CX Codex +1 147installs sensor-calibration-workbench The sensor-calibration-workbench skill guides sensor calibration from warm-up and reference readings to coefficient storage and drift checks for CO2, load-cell, magnetic, color, and analog sensors. CX Codex +1 137installs i2c-bringup-diagnostician i2c-bringup-diagnostician diagnoses I2C bring-up failures on Arduino and ESP32 boards, covering wiring, scanner mismatches, and driver bugs. CX Codex +1 134installs freertos-patterns freertos-patterns picks the right FreeRTOS pattern for ESP32 tasks or RP2040 dual-core work: queues, mutexes, notifications, stack checks. CX Codex +1 120installs mermaid-diagram-generator mermaid-diagram-generator is a Claude Code skill that turns Arduino code and embedded-system behavior into Mermaid diagrams for mapping states, signal sequences, and FreeRTOS task architecture. CX Codex +1 113installs field-power-and-connectivity-triager field-power-and-connectivity-triager is a Claude Code skill that investigates power and connectivity faults when a board works over USB but fails on its intended supply. It checks voltage drops, current peaks, regulators, and wiring. CX Codex +1 113installs arduino-serial-monitor arduino-serial-monitor is a Claude Code skill that reads and analyzes Arduino serial output, including boot logs, sensor data, and communication failures. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open