Menu
Diagnose broken, slow, or confusing Luxonis/OAK apps and device setups.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Build a thin, runnable Luxonis/OAK proof of concept from a project brief by adapting a known-good example.
Interview the user and produce a buildable Luxonis project brief.
Bring a Luxonis OAK camera to a verified device-ready state.
Choose the right Luxonis skill for your current situation.
| name | luxonis-troubleshoot |
| description | Diagnose broken, slow, or confusing Luxonis/OAK apps and device setups. |
| disable-model-invocation | true |
| argument-hint | symptom, error/log, or app path |
| metadata | {"author":"luxonis","version":"1.0.0","status":"stable"} |
Diagnose a broken, slow, or confusing Luxonis/OAK app or device. This is the general
"something is wrong" entry: never refuse, triage, and either fix it or hand off a clean
support packet. Be self-sufficient -- do not assume any other Luxonis skill is installed.
Reference docs and support@luxonis.com, not sibling skills.
End in exactly one state:
SUPPORT_PACKET.md written with the likely
owner and next action.Change one thing, rerun the same reproduction, observe. Never stack changes. Never declare fixed without a passing rerun.
Read the working directory and the user's input. If present, read DEVICE.md and
PROJECT_BRIEF.md. Do not re-interrogate the user about facts a prior session already
captured.
DEVICE.md -- a hint of a previously verified device (model/family/connection/id), not
ground truth. Use it as a starting point, but trust live discovery and debug logs over it:
DHCP, re-cabling, or re-adoption can make it stale, and when the record disagrees with what
the device actually reports, believe the live device and note the drift.PROJECT_BRIEF.md -- tells you what the app is supposed to do; sharpens "wrong output".AGENTS.md/CLAUDE.md as diagnostic source; they are agent guidance.Pin the symptom to a concrete, rerunnable observation. This observation is the definition of fixed.
DEPTHAI_LEVEL=debug (escalate
to trace) to surface XLink/connection/pipeline detail.Use the smallest reliable repro.
One cheap check decides which layer the bug is on: can a minimal known-good DepthAI snippet open the device and stream one frame?
Live DepthAI discovery is the authority here. oakctl list is non-authoritative: RVC2 is
DepthAI-first and never appears in oakctl at all, so an empty oakctl list is not evidence a
device is missing -- confirm with DepthAI discovery before concluding a device is unavailable.
/luxonis-device-setup if the user has it installed -- otherwise continue here. A
hardware fault (orange LED, boot failure, suspected calibration) is a hard stop ->
support-packet to support@luxonis.com.Never reason about the DepthAI API from memory. Confirm every API claim against a
known-good example or the docs, and confirm the depthai version before touching
version-sensitive code -- always DepthAI v3, never v2.
For the app-layer diff, use ~/.luxonis/agent-context/oak-examples as the example reference --
only when a comparison actually helps, not routinely. Source it the same safe way as a build:
~/.luxonis/agent-context (in the user's home) if it does not exist.https://github.com/luxonis/oak-examples over HTTPS (never SSH), shallow and
pinned to main (which tracks DepthAI v3), with git's low-speed guard
(http.lowSpeedLimit=1000, http.lowSpeedTime=60) so a stalled network aborts instead of
hanging. Clone into a temporary sibling path (e.g. oak-examples.tmp) and rename it into
place only on success, using commands appropriate to the host shell, so a failed clone never
leaves a partial checkout behind. If the checkout already exists, refresh it with a
fast-forward-only pull instead.INDEX.md. If the clone fails or is incomplete, do
the diff from live docs instead; never diff against a partial checkout or an older/v2 example.Change exactly one thing, rerun the repro, observe. Add a print/log only if the repro does not already show the answer.
Use this only to pick the right repro and the right page fast. The fixes live in the docs.
| Symptom | Layer | Docs |
|---|---|---|
| Device not found / discovery | device | Device Information; OAK4 / USB getting-started |
| Linux USB permissions, PoE / network / LED | device | USB / OAK4 getting-started; troubleshooting index |
| Device bricked / won't boot | device -> support | my-device-is-bricked |
| Pipeline crash / error | app | diff vs known-good example |
| Bad stereo / depth | app | StereoDepth node |
| Low FPS / latency | app | my-app-is-slow; optimizing |
| Neural network issues | app | neural-network-issues |
| V2 / V3 confusion | version | v2-vs-v3 |
pip or project-dependency changes -> confirm first.
Non-privileged diagnosis (isolated venv, reading logs, rerunning the repro) runs freely.Write SUPPORT_PACKET.md in the current working directory only when local fixing is
exhausted, then tell the user to send it to support@luxonis.com.
# Luxonis Support Packet: <one-line symptom>
## Symptom
What's wrong + the concrete repro observation (command output / measured FPS / frame).
## Environment
OS, Python, depthai version, oakctl version if used, connection (USB/PoE),
device model/family/id (from DEVICE.md if present).
## Device state
Discovered? Verified working before? LED state. Managed vs factory.
## What I tried
One line per hypothesis: change -> rerun result.
## Logs / errors
Smallest relevant excerpt (include DEPTHAI_LEVEL=debug output if relevant).
## Likely owner / next action
Best-guess category (device / network / app / depth / performance / version) + next step.
depthai and oakctl versions are mandatory so support can spot V2/V3 issues immediately.
oakctl is expected to gain a support-file/bundle command; once it exists, prefer generating
that over the ad-hoc levers above.