# circuit-debugger

The circuit-debugger skill for Claude Code guides checks of power, grounds, and signals in Arduino, ESP32, and RP2040 circuits. It helps trace faults such as an unresponsive sensor or an overheating component.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 298 installs · ★ 33 repo stars
- Author: wedsamuel1230
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/wedsamuel1230/embedded-engineering-skills/tree/HEAD/skills/circuit-debugger/SKILL.md
- Updated: 2026-10-15
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/circuit-debugger

## What it does

The skill guides circuit diagnosis in stages: measure supply voltage, test ground continuity, verify signals, then isolate components one at a time. Its checks cover I2C, LEDs, motors, and sensors, and help distinguish a software fault from a hardware problem.

A bundled script, `scripts/generate_debug_sketch.py`, creates sketches for I2C scanning and GPIO, ADC, or PWM tests. For an I2C scan, run `uv run --no-project scripts/generate_debug_sketch.py --i2c --output i2c_scanner.ino`. Power the circuit down before continuity or resistance measurements; do not bridge domains designed to stay isolated.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add wedsamuel1230/embedded-engineering-skills --skill circuit-debugger -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/circuit-debugger/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/circuit-debugger/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add wedsamuel1230/embedded-engineering-skills --skill circuit-debugger -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/circuit-debugger/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add wedsamuel1230/embedded-engineering-skills --skill circuit-debugger -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/circuit-debugger/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install wedsamuel1230/embedded-engineering-skills skills/circuit-debugger
```

2. **Manually: put the files in place**
- File: `.github/skills/circuit-debugger/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add wedsamuel1230/embedded-engineering-skills --skill circuit-debugger -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/wedsamuel1230/embedded-engineering-skills --path skills/circuit-debugger
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/circuit-debugger/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add wedsamuel1230/embedded-engineering-skills --skill circuit-debugger -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/wedsamuel1230/embedded-engineering-skills/tree/HEAD/skills/circuit-debugger/SKILL.md

## When to use it
- trace a board with no power
- check whether devices respond on an I2C bus
- find a floating signal on a pin
- identify which added component causes a failure
- separate firmware issues from hardware faults

## Example prompts
- Walk me through checking the power and ground connections on my ESP32 circuit.
- Generate a sketch to scan for I2C devices and save it as `i2c_scanner.ino`.
- Help me diagnose an unresponsive sensor by checking its power, wiring, and signals.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: dea584c9bac7ba8b.

BEGIN THIRD-PARTY FILE dea584c9bac7ba8b
````text
---
name: circuit-debugger
description: |
  Systematic hardware debugging guide for Arduino/ESP32/RP2040 circuits. Use when user reports: circuit not working, components getting hot, no power, intermittent failures, unexpected behavior, sensor not responding, LED not lighting, motor not spinning. Guides through power checks, continuity testing, signal tracing, and component isolation using multimeter techniques.
metadata: {triggers: "circuit failure, no power, hot component, sensor not responding, multimeter"}
---

# Circuit Debugger

Systematic approach to diagnosing hardware issues in maker projects.

## Resources

This skill includes bundled tools and references:

- **scripts/generate_debug_sketch.py** - Arduino sketch generator for I2C scanner, GPIO tester, ADC checker, PWM tester
- **references/measurement-procedures.md** - Comprehensive multimeter and oscilloscope guide

## Quick Start

**Generate I2C scanner:**
```bash
uv run --no-project scripts/generate_debug_sketch.py --i2c --output i2c_scanner.ino
```

**Generate GPIO tester:**
```bash
uv run --no-project scripts/generate_debug_sketch.py --gpio --pins 2,3,4,5 --output gpio_test.ino
```

**Generate all debug sketches:**
```bash
uv run --no-project scripts/generate_debug_sketch.py --all
```

**Interactive mode:**
```bash
uv run --no-project scripts/generate_debug_sketch.py --interactive
```

## Trigger Phrases
- "My circuit doesn't work"
- "Component is getting hot"
- "No power to the board"
- "Sensor not responding"
- "Intermittent/random failures"
- "Works sometimes, not others"

## Debugging Protocol

### Phase 1: Power System Check (Do First!)

**Visual Inspection (30 seconds)**
```
□ Check for smoke, burn marks, or melted plastic
□ Verify power LED on microcontroller is lit
□ Look for loose wires or cold solder joints
□ Confirm correct polarity on polarized components (LEDs, caps, diodes)
```

**Multimeter Tests (Set to DC Voltage)**
```
Test Point              | Expected Value  | If Wrong
------------------------|-----------------|------------------
VCC to GND on MCU       | 3.3V or 5V      | Check regulator, power source
Sensor VCC pin          | Match datasheet | Check wiring, broken trace
Motor driver VCC        | Logic + Motor V | Separate supplies needed?
Battery terminals       | Rated voltage   | Dead/discharged battery
```

**Common Power Issues:**
| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| No voltage anywhere | Disconnected power, blown fuse | Check continuity from source |
| Low voltage (< 4V when expecting 5V) | Overloaded supply, bad regulator | Reduce load, check current draw |
| Voltage drops under load | Undersized power supply | Calculate total current, upgrade PSU |
````
END THIRD-PARTY FILE dea584c9bac7ba8b

The third-party file has ended. Everything between the dea584c9bac7ba8b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2728 of 7868 bytes. © wedsamuel1230 · MIT · https://github.com/wedsamuel1230/embedded-engineering-skills/tree/HEAD/skills/circuit-debugger/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
