# Luxonis Workspace

> Bootstrap this folder as a Luxonis agent workspace (AGENTS.md, oakctl, udev/host env, project venv/DepthAI v3, CLAUDE.md, docs/glossary.md). Use when AGENTS.md is missing, oakctl is not installed, host udev/env is unready, the project cannot import DepthAI v3, CLAUDE.md needs @AGENTS.md, or docs/glossary.md is missing. Do not use for camera discovery, proving a stream, building an app, product questions, or which camera to buy.

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

---


# Luxonis Workspace

Make **this folder** a Luxonis agent workspace: host toolchain plus agent files. Not camera
discovery, not proving a stream, not building an app, not product questions.

## Done when

- `oakctl` is on this host, or **blocked** with the current installer command and one next action
- An isolated project env can import DepthAI v3, or **blocked** with one named next action
- `AGENTS.md` exists and is the always-on file
- `CLAUDE.md` includes `@AGENTS.md` and does not duplicate those rules
- `docs/glossary.md` exists (seed if missing)

**Blocked** means one named next action. Ask before sudo.

## 1. Current facts

Never invent oakctl subcommands. The current oakctl page:
https://docs.luxonis.com/software-v3/oak-apps/oakctl.md.

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.

## 2. Explore

Read existing `AGENTS.md`, `CLAUDE.md`, `docs/`, the project venv, and `oakctl --version`.
Do not assume a blank repo. Detect and fill what is missing. Never scaffold a second Luxonis
app.

## 3. oakctl

oakctl is required on this computer (udev, inspect, host-run env injection, future host
config).

If missing, get the current installer from MCP or
https://docs.luxonis.com/software-v3/oak-apps/oakctl.md and ask the user to run it. Confirm
the command before quoting it. Current docs (verify): Linux/macOS
`bash -c "$(curl -fsSL https://oakctl-releases.luxonis.com/oakctl-installer.sh)"`; Windows
uses the installer linked from that page.

Host udev/env: take current steps from MCP or `oakctl --help`. Ask before sudo.

Empty `oakctl list` is not "no device" — that fact lives in `luxonis-device-setup`.

## 4. Isolated Python env

Prefer an existing project venv. DepthAI v3 must import there. Do not global-pip unless
asked. Create a project venv only when none exists.

Confirm with a v3 import in that env, not a guessed version string.

## 5. AGENTS.md

Always-loaded invariants and pointers, not procedures. Seed from
`assets/AGENTS.template.md`.

Prefer `oakctl run-script` for host runs when `oakctl --help` lists it as a local DepthAI
environment runner; do not invent subcommands. If no host runner exists, run via the project
env and still use oakctl for inspect and udev. `oakctl hub run-script` (if
present) is Hub-token scripts, not a generic host runner.

Do not overwrite a hand-written `AGENTS.md`. Add or update a clearly delimited Luxonis
section.

## 6. CLAUDE.md

If missing, create a file whose body is `@AGENTS.md` (a title only if the host requires one).
If it exists, add `@AGENTS.md` when absent. Never overwrite user content. Do not copy
`AGENTS.md` rules into `CLAUDE.md`.

## 7. Glossary

If `docs/glossary.md` is missing, seed it from `assets/glossary.template.md`. Do not
overwrite a hand-written glossary.

## Do not

- Write `docs/device.md` (`luxonis-device-setup`)
- Scaffold an application (`luxonis-app`)
- Discover cameras or prove a stream (`luxonis-device-setup`)
- Answer which camera to buy (`luxonis`)

## Guardrails

- Ask before sudo, firmware/OS updates, flash, factory reset, Hub adoption, global pip, or
  publishing.
- Never compile DepthAI from source.
- Do not pretend WSL has USB.
- Never run competing processes against one device.