# Luxonis Model

> Convert or integrate a custom model into an OAK app. Do not use to train a model or to pick a Zoo model for a new app.

- Skill: `luxonis/luxonis-model` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add luxonis/luxonis-model`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luxonis/luxonis-model/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: luxonis (https://skillmd.com/u/luxonis)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/luxonis/luxonis-model

---


# Luxonis Model

Take a **custom** (not already Zoo-ready) model to a target NN Archive and wire it into the
OAK app. One skill for convert and integrate.

## Done when

The archive is on disk with a checked contract, and it is wired into the app when that was
requested. Live model behavior is proven when a device or replay (`luxonis-record`) is
available; otherwise name the pending runtime check. **Blocked** means one named next
action.

Never invent DepthAI APIs from memory. DepthAI v3 only; do not mix v2 APIs.

Best source first: the Luxonis MCP tools (surfaced names vary by host), then the exact example
or doc source they return, then `https://docs.luxonis.com/llms.txt`, then observed behavior;
memory is only for general reasoning. For oakctl commands and flags, the installed
`oakctl --help` outranks docs and MCP: the local version (possibly older or beta) defines what
is possible here, so work from it and suggest an oakctl update when it lacks something current
docs describe. If observed host or device behavior contradicts docs or MCP, trust the
observation and note the conflict. If offline, work from `oakctl --help` and local examples and
name which facts are unverified.

If `AGENTS.md` is missing, or oakctl is missing when this job needs the host toolchain, name
`luxonis-workspace` and follow it, then continue. Do not copy its procedure.

Read `docs/brief.md`, `docs/device.md`, source, and any existing archive or conversion note
when present. Also read legacy root `PROJECT_BRIEF.md` and `DEVICE.md` if present. None is
required. Treat `docs/device.md` as setup notes; trust live state. Do not start a greenfield
interview. If the product is wrong, or the job is picking a Zoo model for a new app, mention
`luxonis-app`.

## 1. Choose the branch

- Source is ONNX, TFLite, OpenVINO IR, or another non-archive artifact → convert
  (`references/convert.md`), then integrate if the app should use it.
- Source is already a target-compatible NN Archive → integrate (`references/integrate.md`).
- Training, dataset collection, or choosing a Zoo model for a new app → say so and stop.

## 2. Keep the contract explicit

Before converting or wiring, know:

- Target device and RVC family. RVC2 and RVC4 artifacts are not interchangeable.
- Exact source artifact, checksum, publisher, and accepted license.
- Input names, shapes, layout, dtype, color, and preprocessing.
- Output names, shapes, heads/parser, and label or keypoint order.
- A small representative input set.

Stop rather than guess tensor semantics. Approval of a named third-party model revision and
license authorizes that download. Cloud upload stays a separate explicit ask.

NN Archive metadata is the source of truth for inputs, preprocessing, heads/parser, and
labels. Run `scripts/validate_nn_archive.py` against that contract. Metadata passing is not
proof of useful inference.

## 3. Verify the model path

After convert and/or integrate, compare representative source versus converted behavior when
a supported runtime exists. For live pipeline claims, use `luxonis-inspect`.

If conversion details would help the next session, write a short note next to the archive
(path, target, checksum, parser, labels). That note is not a gate.

## Guardrails

- Ask before cloud upload, global pip, or publishing an archive.
- Never compile DepthAI from source.
- Never run competing processes against one device.