{
  "markdown": "# arduino-skills\n\n![Status](https://img.shields.io/badge/version-1.8.0-blue)\n![Skills](https://img.shields.io/badge/skills-30%20packages%20on%20main-brightgreen)\n![Platform](https://img.shields.io/badge/platform-Arduino%20%7C%20embedded-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n![Marketplace](https://img.shields.io/badge/marketplace-claude%20%26%20gemini-orange)\n\n> Professional Arduino/embedded systems skills and maker tools for development, education, and prototyping.  \n> v1.8.0: toolchain-neutral,\n> board-aware Arduino skills with plugin packaging,\n> physical-world evidence gates, and composable lifecycle workflows for OTA deployment, calibration,\n> field-power triage, and I2C bring-up.\n\n## 📋 Table of Contents\n\n- [arduino-skills](#arduino-skills)\n  - [📋 Table of Contents](#-table-of-contents)\n  - [🔍 Overview](#-overview)\n  - [🤖 How Skills Work](#-how-skills-work)\n  - [📦 Installation](#-installation)\n    - [Quick Install (Recommended and Easiest)](#quick-install-recommended-and-easiest)\n    - [Manual Setup](#manual-setup)\n  - [🚀 Quick Start](#-quick-start)\n    - [Generate Code Snippets](#generate-code-snippets)\n    - [Scaffold Complete Projects](#scaffold-complete-projects)\n  - [🔧 Arduino Core Skills](#-arduino-core-skills)\n    - [Pattern Relationships](#pattern-relationships)\n  - [🛠️ Maker Tools](#️-maker-tools)\n    - [Tool Scripts](#tool-scripts)\n  - [🏗️ Project Builders](#️-project-builders)\n    - [Code Generator Workflow](#code-generator-workflow)\n    - [Project Builder Workflow](#project-builder-workflow)\n  - [📱 Platform Support](#-platform-support)\n    - [Board-Specific Optimization](#board-specific-optimization)\n  - [🏛️ Architecture](#️-architecture)\n    - [Directory Structure](#directory-structure)\n    - [Release And Tags](#release-and-tags)\n    - [Design Principles](#design-principles)\n  - [🤝 Contributing](#-contributing)\n    - [Quick Submission Checklist](#quick-submission-checklist)\n  - [📖 Documentation](#-documentation)\n  - [📄 License](#-license)\n  - [📋 Changelog](#-changelog)\n\n---\n\n## 🔍 Overview\n\nThis collection provides production-ready skills for Arduino and maker projects:\n\n- **Arduino Core Skills** - Hardware patterns, timing, communication, FreeRTOS, and CLI workflows\n- **Maker Tools** - Debugging, serial monitoring, BOM generation, power planning, documentation, diagrams\n- **Project Builders** - Code generation and project scaffolding with automation scripts\n- **Board Support** - AI-facing exact-board lookup, source status, capability tags, and safe pin handoff\n- **Workflow Router** - Board/toolchain intake and combined firmware, electronics, power, networking, enclosure, and deployment workflows\n\nThe workflow is toolchain-neutral across Arduino IDE, Arduino CLI, PlatformIO,\nand vendor-specific tools. The exact board, framework, versions, and hardware\nevidence determine what can be claimed for a task.\n\nAll skills follow a consistent structure with:\n- ✅ Copy-paste ready code that compiles without warnings\n- ✅ Verification steps with expected outputs\n- ✅ Common pitfalls with corrections\n- ✅ Engineering rationale explaining \"why\"\n\n---\n\n## 🤖 How Skills Work\n\n**arduino-skills** uses the **Agent Skills** open format for self-contained,\ninteroperable agent capabilities. Each skill is a folder containing:\n\n- **SKILL.md** — Instructions with YAML frontmatter (`name`,\n  `description`, optional spec fields)\n- **scripts/** — Python automation tools with PEP 723 inline dependencies\n- **references/** — Code examples, patterns, and templates\n- **assets/** — Diagrams, datasheets, and resources\n\nSkills follow progressive disclosure:\n\n1. Discovery loads only `name` and `description`\n2. Activation loads the main `SKILL.md`\n3. Detailed references and scripts are loaded only when needed\n\nThe main `SKILL.md` should stay focused. Heavy examples, troubleshooting, and\ndeep reference material belong in `references/`, `scripts/`, or `assets/`.\n\nFor a complete request, start with `arduino-workflow-router`. For any request\nthat spans physical hardware, recovery, measurements, or multiple sessions,\nload `embedded-project-loop` first. It creates the durable goal, one next todo,\nevidence ledger, rollback path, and user-owned physical gate before the router\ncomposes specialists. For a named board reference or capability lookup, start\nwith `board-support`; for choosing or replacing a board from requirements, use\n`board-selection`. Neither entry point assumes Arduino IDE, a particular\nboard family, or a successful compile as proof of system behavior.\n\n\n---\n\n## 📦 Installation\n\n### Quick Install (Recommended and Easiest)\n\n```bash\nnpx skills add wedsamuel1230/arduino-skills\n```\n\n### Plugin Hosts\n\nThe repository has one shared `skills/` source of truth and thin adapters for\nthe major hosts:\n\n| Host | Install or test command | Adapter |\n|---|---|---|\n| Agent Skills CLI | `npx skills add wedsamuel1230/arduino-skills` | `skills/` |\n| Codex | `codex plugin marketplace add /path/to/arduino-skills` then `codex plugin add arduino-skills@arduino-skills` | `.codex-plugin/` |\n| Claude Code | `claude --plugin-dir /path/to/arduino-skills` | `.claude-plugin/` |\n| Cursor | Open/install the repo as a plugin | `.cursor-plugin/` |\n\nSee [docs/plugin-distribution.md](docs/plugin-distribution.md) for published\nmarketplace flows, wrapper conventions, and validation commands.\n\n### Manual Setup\n1. **Clone the Repository**\n\n```bash\ngit clone https://github.com/wedsamuel1230/arduino-skills.git\ncd arduino-skills\n\n```\n\n2. **Copy Skills to Extensions Directory**\n```bash\n# Example: install into Codex's local skills directory\nmkdir -p ~/.codex/skills\n\n# Copy all skills\ncp -r skills/* ~/.codex/skills/\n```\n---\n\n\n## 🚀 Quick Start\n\n### Generate Code Snippets\n\n```bash\n# List available patterns\nuv run skills/arduino-code-generator/scripts/generate_snippet.py --list\n\n# Generate I2C scanner for ESP32\nuv run skills/arduino-code-generator/scripts/generate_snippet.py --pattern i2c --board esp32\n\n# Interactive mode\nuv run skills/arduino-code-generator/scripts/generate_snippet.py --interactive\n```\n\n### Scaffold Complete Projects\n\n```bash\n# List project types\nuv run skills/arduino-project-builder/scripts/scaffold_project.py --list\n\n# Create environmental monitor for ESP32\nuv run skills/arduino-project-builder/scripts/scaffold_project.py \\\n    --type environmental --board esp32 --name \"WeatherStation\"\n\n# Interactive mode\nuv run skills/arduino-project-builder/scripts/scaffold_project.py --interactive\n```\n\n### Route A Complete Workflow\n\nUse `arduino-workflow-router` when the request combines implementation with\nboard constraints, power, networking, calibration, enclosure, upload, OTA, or\nmaintenance. The router selects the smallest useful sequence and keeps build,\nupload, hardware, system, and deployment evidence separate.\n\n---\n\n## 🔧 Arduino Core Skills\n\n| Pattern | Path | Description |\n|-------|------|-------------|\n| Button Debouncing | `arduino-code-generator/` | Software debouncing with press/release/long-press detection |\n| Config Management | `arduino-code-generator/` | Multi-board hardware abstraction with conditional compilation |\n| CSV Output | `arduino-code-generator/` | Structured data logging for Serial/SD/Excel analysis |\n| Data Logging | `arduino-code-generator/` | EEPROM with CRC, SD card CSV, wear leveling |\n| ADC Filtering | `arduino-code-generator/` | Moving average, median, and Kalman filters for noisy sensors |\n| Hardware Detection | `arduino-code-generator/` | Auto-detect boards, sensors, adaptive configuration |\n| I2C Communication | `arduino-code-generator/` | Device scanning, address detection, bus diagnostics |\n| Non-blocking Scheduler | `arduino-code-generator/` | millis()-based timing, priority task scheduling |\n| State Machine | `arduino-code-generator/` | Enum-based FSM for complex behavior control |\n\n### Pattern Relationships\n\n```mermaid\n%%{init: {\n  \"theme\": \"neutral\",\n  \"themeVariables\": {\n    \"primaryColor\": \"#df9696ff\",\n    \"primaryTextColor\": \"#0f8cf3ff\",\n    \"lineColor\": \"#4A77B5\"\n  }\n}}%%\nmindmap\n  root((Arduino Patterns))\n    Hardware\n      Config Management\n      Hardware Detection\n      I2C Communication\n    Input\n      Button Debouncing\n      ADC Filtering\n    Timing\n      Non-blocking Scheduler\n      State Machine\n    Output\n      CSV Output\n      Data Logging\n    Projects\n      Environmental Monitor\n      Robot Controller\n      IoT Device\n```\n\n---\n\n## 🛠️ Maker Tools\n\n| Skill | Path | Description |\n|-------|------|-------------|\n| Circuit Debugger | `circuit-debugger/` | 5-phase hardware debugging with multimeter guide |\n| Error Explainer | `error-message-explainer/` | Compiler error interpretation with fixes |\n| BOM Generator | `bom-generator/` | Bill of materials with supplier links, Excel export |\n| Power Calculator | `power-budget-calculator/` | Current draw estimation, battery sizing |\n| Battery Selector | `battery-selector/` | Chemistry comparison, charging solutions |\n| Enclosure Designer | `enclosure-designer/` | OpenSCAD parametric templates, 3D print settings |\n| README Generator | `readme-generator/` | Professional GitHub documentation |\n| Code Review | `code-review-facilitator/` | 8-category review, code smell detection |\n| Datasheet Interpreter | `datasheet-interpreter/` | PDF spec extraction from URLs |\n| **Serial Monitor** | `arduino-serial-monitor/` | Enhanced serial debugging with real-time monitoring, data logging, filtering, and error detection |\n| **Mermaid Generator** | `mermaid-diagram-generator/` | Visual documentation: state machines, timing, FreeRTOS |\n| **OTA Deployment** | `ota-deployment-guardian/` | OTA-safe deployment workflows, network port recovery, and remote update guardrails |\n| **Calibration Workbench** | `sensor-calibration-workbench/` | Calibration workflows, coefficient persistence, and drift checks for maker sensors |\n| **Sensor Signal Filtering** | `sensor-signal-filtering/` | ADC/sensor filter selection, analog front-end checks, and evidence-gated TDD |\n| **Field Power Triage** | `field-power-and-connectivity-triager/` | USB-vs-field-power diagnosis for WiFi and sensor-heavy maker projects |\n| **I2C Bringup** | `i2c-bringup-diagnostician/` | Fault isolation for I2C detection, library, pull-up, and board-quirk failures |\n| **Board Support** | `board-support/` | Exact-board profile lookup, capability/risk tags, source confidence, framework boundaries, and pin handoff |\n| **Workflow Router** | `arduino-workflow-router/` | Board/toolchain intake, combined workflow routing, recovery, security, and evidence stages |\n\n### Engineering Guardrails\n\n| Skill | Path | Description |\n|---|---|---|\n| Board Selection | `board-selection/` | Choose an exact board from voltage, pins, memory, power, toolchain, and recovery requirements |\n| Pin Assignment | `pin-assignment/` | Check physical GPIO constraints while preserving ordered raw `constexpr int` declarations |\n| Wiring Safety | `wiring-safety-check/` | Check logic levels, current, pull-ups, drivers, rails, and safe defaults |\n| Non-blocking Patterns | `non-blocking-patterns/` | Replace blocking timing with tested C++ scheduling, debounce, and state transitions |\n| Library Selection | `library-selection/` | Compare architecture, version, footprint, maintenance, and security fit |\n| Memory Budgeting | `memory-budgeting/` | Budget flash, SRAM, heap, stack, partitions, and runtime margin |\n| Hardware TDD | `hardware-tdd/` | Separate host, simulation, build, target, and system tests |\n| **Embedded Project Loop (recommended for physical work)** | `embedded-project-loop/` | Durable next-todo state, evidence logs, bounded changes, rollback, and physical gates |\n\n### Tool Scripts\n\nAll tools include Python scripts with PEP 723 inline dependencies:\n\n```bash\n# Serial monitoring with filtering and error detection\nuv run skills/arduino-serial-monitor/scripts/monitor_serial.py --port COM3 --detect-errors\n\n# Power budget calculation\nuv run skills/power-budget-calculator/scripts/calculate_power.py --interactive\n\n# BOM generation to Excel\nuv run skills/bom-generator/scripts/generate_bom.py --output bom.xlsx\n\n# Extract specs from datasheet PDF\nuv run skills/datasheet-interpreter/scripts/extract_specs.py \\\n    --url \"https://example.com/sensor-datasheet.pdf\"\n```\n\n---\n\n## 🏗️ Project Builders\n\n### Code Generator Workflow\n\n```mermaid\nflowchart TD\n    A[\"User Request: Generate Arduino Code\"] --> B{\"Pattern Type?\"}\n    \n    B -->|config| C1[\"patterns-config.md\"]\n    B -->|buttons| C2[\"patterns-buttons.md\"]\n    B -->|i2c| C3[\"patterns-i2c.md\"]\n    B -->|other| C4[\"...\"]\n    \n    C1 & C2 & C3 & C4 --> D[\"Template Engine generate_snippet.py\"]\n    \n    D --> E{\"Board Type?\"}\n    \n    E -->|Arduino UNO| F1[\"2KB SRAM 9600 baud\"]\n    E -->|ESP32| F2[\"520KB SRAM WiFi/BLE\"]\n    E -->|RP2040| F3[\"264KB SRAM Dual-core\"]\n    \n    F1 & F2 & F3 --> G[\"Generated .ino Code\"]\n```\n\n### Project Builder Workflow\n\n```mermaid\nflowchart TD\n    A[\"📋 Requirements\"] --> B[\"🔧 Hardware Inventory\"]\n    B --> C[\"🎯 Board Selection\"]\n    C --> D{\"Project Type?\"}\n    \n    D -->|Environmental| E1[\"DHT22, Light, Logging, SD Card\"]\n    D -->|Robot| E2[\"Ultrasonic, Motors, Servo\"]\n    D -->|IoT| E3[\"BME280, WiFi, MQTT\"]\n    \n    E1 & E2 & E3 --> F[\"📦 Pattern Assembly scaffold_project.py\"]\n    \n    F --> G[\"📁 Project Structure\"]\n    \n    G --> H1[\"src/config.h\"]\n    G --> H2[\"src/main.ino\"]\n    G --> H3[\"platformio.ini\"]\n    G --> H4[\"README.md\"]\n    \n    H1 & H2 & H3 & H4 --> I[\"✅ Complete Project\"]\n```\n\n---\n\n## 📱 Platform Support\n\n| Platform | SRAM | Features | Skills Supported |\n|----------|------|----------|------------------|\n| **Arduino UNO/Nano** | 2KB | Basic I/O, ADC | All (with F() macro) |\n| **ESP32** | 520KB | WiFi, BLE, dual-core, FreeRTOS | All + IoT projects |\n| **RP2040 (Pico)** | 264KB | Dual-core, PIO, USB host | All (no WiFi unless Pico W) |\n\n### Board-Specific Optimization\n\nThe board table below is a set of reference profiles, not an exhaustive support\nclaim. Always confirm the exact model, revision, pin map, memory, peripherals,\nvoltage/current limits, protocols, framework, and recovery path before applying\nboard-specific advice.\n\nThe exact-profile inventory is maintained in\n[`references/boards/index.json`](references/boards/index.json), including\nMega 2560 Rev3, Nano Every, Nano ESP32, and ESP32-C3-DevKitC-02. A profile is\ndocumentation support, not a claim that the current checkout has been built,\nuploaded, wired, or measured on that board.\n\nFor AI retrieval, the index carries compact aliases, MCU/architecture, logic\nlevel, capability tags, risk tags, identity contracts, toolchain families, and\nevidence status. Resolve names with the deterministic\n`scripts/resolve_board_profile.py` helper, then read the linked Markdown\nprofile and the [AI reference schema](references/boards/ai-reference-schema.md)\nbefore assigning pins or making electrical claims. A generic family match is\nnot a variant confirmation.\n\n\n|Arduino UNO (2KB)     |ESP32 (520KB)       |RP2040(264KB)   |\n|----------------------|--------------------|----------------|\n| F() for strings      | WiFi/BLE patterns  | Multicore tasks|\n| Small buffers        | FreeRTOS tasks     | PIO for timing |\n| Avoid String class   | Large JSON buffers | USB host mode  |\n| 9600 baud            | 115200 baud        | 115200 baud    |\n\nThe profile set now also covers Mega 2560 Rev3, Nano Every, Nano ESP32, and\nESP32-C3-DevKitC-02. Use `references/boards/index.json` for the exact\nboard-to-profile inventory; this table is only a family-level orientation.\n\n\n---\n\n## 🏛️ Architecture\n\n### Directory Structure\n\n```\n.\n├── README.md\n├── CONTRIBUTING.md\n├── DEVELOPMENT.md\n├── CHANGELOG.md\n├── plugin.json                         # portable plugin metadata\n├── .codex-plugin/plugin.json           # Codex plugin manifest\n├── .claude-plugin/                     # Claude Code adapter and marketplace\n├── .cursor-plugin/                     # Cursor adapter and marketplace\n├── .agents/plugins/marketplace.json    # Codex repository marketplace\n├── AGENTS.md / CLAUDE.md / GEMINI.md   # thin host wrappers\n├── arduino-skills.md\n├── docs/\n│   ├── board-support/                # Shared board-family support references\n│   ├── diagrams/                     # Mermaid diagram sources\n│   ├── plugin-distribution.md         # Host install and source-of-truth rules\n│   ├── releases/                      # Versioned release notes\n│   ├── research/                     # Archived discovery and pain-point research\n│   └── workflows/                    # Archived PRD, plan, and test-map artifacts\n├── scripts/\n│   ├── validate_agent_skills.py      # Agent Skills schema validator\n│   ├── validate_arduino_skill_contract.py # Cross-skill lifecycle contract validator\n│   ├── validate_arduino_plugin.py     # Plugin, reference, and eval validator\n│   └── resolve_board_profile.py       # Exact board lookup and identity gate\n├── evals/\n│   ├── evals.json                     # Prompt and routing scenarios\n│   └── fixtures/loop-engine/          # Durable-loop positive/negative fixtures\n└── skills/\n    ├── arduino-workflow-router/      # Concise universal router\n    ├── board-support/                # AI-facing exact-board reference lookup\n    ├── board-selection/\n    ├── pin-assignment/\n    ├── wiring-safety-check/\n    ├── non-blocking-patterns/\n    ├── library-selection/\n    ├── memory-budgeting/\n    ├── hardware-tdd/\n    ├── embedded-project-loop/\n    ├── arduino-code-generator/\n    ├── arduino-project-builder/\n    ├── arduino-cli-skill/\n    ├── ota-deployment-guardian/\n    ├── sensor-calibration-workbench/\n    ├── field-power-and-connectivity-triager/\n    ├── i2c-bringup-diagnostician/\n    └── ...                           # Remaining Arduino and maker skills\n```\n\n### Release And Tags\n\n`SKILL.md` is the canonical source of truth for skill authoring and discovery.\n`skills/` is also the single content source for the Codex, Claude Code, Cursor,\nand Agent Skills CLI adapters.\nBefore publishing a release, run:\n\n```bash\npython3 scripts/validate_agent_skills.py\npython3 scripts/validate_arduino_skill_contract.py\npython3 scripts/validate_arduino_plugin.py\npython3 scripts/run_arduino_evals.py --output evals/eval-results.json\nUV_CACHE_DIR=/private/tmp/arduino-skills-uv-cache uv run --no-project --with pyyaml \\\n  /Users/wed/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .\n```\n\nFor release `v1.8.0`, the tag and push commands are:\n\n```bash\ngit tag -a v1.8.0 -m \"Release v1.8.0\"\ngit push origin main v1.8.0\n```\n\nSuggested repository topics for hosting platforms:\n\n- `arduino`\n- `embedded`\n- `agent-skills`\n- `makers`\n- `esp32`\n- `rp2040`\n- `uno-r4`\n- `ota`\n- `i2c`\n- `calibration`\n\n### Design Principles\n\nAll skills follow these rules from `arduino-skills.md` and the shared contract:\n\n1. **Verifiable Output** - Every example includes test procedures and expected results\n2. **Avoid delay() Blocking** - Use `millis()` and state machines for timing\n3. **Hardware Abstraction** - All board-specific code in `config.h` with `#if defined()`\n4. **Toolchain Neutrality** - Name the exact IDE, CLI, PlatformIO environment, or vendor tool and its versions\n5. **Evidence Separation** - Keep build, upload, hardware, system, and deployment proof distinct\n6. **Secure Maintenance** - Redact secrets and name update, rollback, dependency, and decommissioning controls\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions. Before you start, read:\n\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Skill submission process, code quality checklist, and pull request workflow\n- **[DEVELOPMENT.md](DEVELOPMENT.md)** — Setup guide, skill creation walkthrough, and automation scripts\n\n### Quick Submission Checklist\n\n- [ ] Compiles without warnings on Arduino IDE\n- [ ] Records the exact board/revision, framework, toolchain, versions, pins, memory, power, and protocols\n- [ ] Names whether evidence is build, upload, hardware, system, or deployment proof\n- [ ] Uses `unsigned long` for millis() timing\n- [ ] Bounds checking on all arrays\n- [ ] F() macro for string constants on UNO\n- [ ] No hardcoded pins (use config.h)\n- [ ] SKILL.md has complete sections and YAML frontmatter\n- [ ] Tested on the exact target (or documents the unverified limitation)\n- [ ] Recovery path and connected-device secret/update handling are documented when relevant\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md#submitting-a-new-skill) for the complete process.\n\n---\n\n## 📖 Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [README.md](README.md) | Main project documentation (this file) |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Skill submission guidelines and checklist |\n| [DEVELOPMENT.md](DEVELOPMENT.md) | Setup, skill creation, automation scripts |\n| [arduino-skills.md](arduino-skills.md) | Design principles and constraints |\n| [docs/arduino-skill-contract.md](docs/arduino-skill-contract.md) | Shared intake, toolchain, evidence, output, security, and lifecycle contract |\n| [docs/board-support/board-profile-template.md](docs/board-support/board-profile-template.md) | Board and hardware intake template |\n| [references/boards/index.json](references/boards/index.json) | Machine-readable board discovery inventory |\n| [references/boards/ai-reference-schema.md](references/boards/ai-reference-schema.md) | AI board lookup fields, evidence, and maintenance rules |\n| [docs/board-support/trigger-evaluation.md](docs/board-support/trigger-evaluation.md) | Held-out board-support activation evaluation contract |\n| [docs/releases/v1.8.0.md](docs/releases/v1.8.0.md) | Current release notes and verification boundary |\n| [docs/releases/v1.7.0.md](docs/releases/v1.7.0.md) | Previous release notes and verification boundary |\n| [evals/evals.json](evals/evals.json) | Prompt-level routing and loop-engine evaluation cases |\n| [CHANGELOG.md](CHANGELOG.md) | Version history and release notes |\n| [docs/research/](docs/research/) | Archived discovery notes and pain-point research |\n| [docs/workflows/](docs/workflows/) | Archived PRD, plan, and verification artifacts |\n\n---\n\n## 📄 License\n\nThese skills are provided under the **MIT** license.  \nSuitable for development, research, and prototyping.\nSee [LICENSE](LICENSE) for details.\n\n## 📋 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for the complete version history and release notes.\n\n---\n",
  "bytes": 22323,
  "sha": "59e2cca620db4ed97a584fd2745128e9a232786ee5432bc9d595beb9a78af296",
  "repo_slug": "wedsamuel1230/arduino-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_wedsamuel1230_arduino_skills_arduino_cli_ea443c49/readme"
}