Onyx Repo Skill

Use this skill when the task is about understanding, changing, testing, or troubleshooting the Onyx repository. Onyx is a Gen-AI application platform with a Python/FastAPI backend, Celery workers, OpenSearch-backed RAG/indexing, Next.js web app, Expo mobile app, Go-based CLIs, Docker/Helm deployment assets, and Enterprise Edition overlays.

Start here, then route to the smallest sub-skill that owns the workflow. Keep runtime work in the target checkout, but use the bundled references first so common Onyx rules do not have to be rediscovered.

Fast Orientation

• Read references/repo-provenance.md before deciding whether this skill is current for a checkout.
• Read references/repo-maintenance.md for cross-cutting contribution, security, testing, and repository-boundary rules.
• Read references/troubleshooting.md when setup, imports, services, secrets, generated files, or local toolchains block progress.
• Run scripts/check_onyx_environment.py for a read-only sanity check of a checkout, optional source imports, and available host tools.

Route Map

Task signal	Read first
FastAPI route, auth/RBAC, SQLAlchemy, Alembic migration, Celery task/queue, file store, backend test, tenant/security boundary	backend-platform
Connector, DocumentSource, credential/permission sync, file-backed document, chunking, embedding, OpenSearch, indexing pipeline, RAG retrieval	rag-indexing-connectors
Chat turn, custom agent/persona, tool/action, MCP, deep research, Craft build mode, sandbox, skills, code execution, agentic streaming	agents-craft-and-tools
Next.js web UI, Opal design system, frontend API proxy, SWR/data fetching, web chat/admin/Craft UI, Jest, Playwright	web-frontend
Expo/React Native mobile app, mobile chat/auth/API, NativeWind, MMKV/TanStack Query, mobile tests, web-parity porting	mobile-client
onyx-cli, ods, Docker Compose, Helm, local service orchestration, deployment lifecycle, generated compose, release/devtools	cli-deployment-devtools

Cross-Cutting Defaults

• Python backend work assumes Python 3.13 and uv; the Onyx root project is not installed as a normal Python distribution, so backend imports normally resolve from the checkout/PYTHONPATH conventions described in the backend references.
• Typical backend setup from a checkout is uv sync --frozen --group backend --group dev --group ee (add specialized groups only when the task requires them). Use the repo-managed .venv or uv run; do not publish private environment prefixes.
• Frontend and mobile JavaScript work assumes Bun-managed dependencies in the relevant package directory, for example bun install --frozen-lockfile from web/ or mobile/ before native JS checks. Do not silently install Bun or Go on a host; report missing toolchains or ask before host-level changes.
• Go source work for cli/ and tools/ods/ needs Go plus the repo-specific command guidance in cli-deployment-devtools.
• Live backend calls should go through the frontend proxy, for example http://localhost:3000/api/..., not the backend port directly.
• Prefer integration tests for product behavior when services are running; use unit tests for isolated logic and external-dependency unit tests when real dependencies are needed without full app processes.
• Test secrets are resolved by Onyx test utilities. Never add API keys, OAuth secrets, service-account JSON, or private tokens to source, tests, fixtures, examples, or generated skill files.
• Destructive operations (DB drop/restore, index reset, deployment uninstall, Helm namespace deletion, force-push/merge/close PRs, audit allowlist upload) require explicit user approval.

Initial Checks

From a checkout, use the bundled environment checker before deep work:

python skills/onyx/scripts/check_onyx_environment.py --repo-root .

When a Python environment is available and you want import evidence:

python skills/onyx/scripts/check_onyx_environment.py --repo-root . --check-python-imports

The checker is read-only. It does not start Onyx services, install packages, contact the network, run tests, or mutate Docker/Kubernetes/DB state.

When Multiple Sub-Skills Apply

• New connector option or source: start with rag-indexing-connectors, then use backend-platform for API/DB/migrations and web-frontend for admin connector form changes.
• Craft issue visible in the web UI: start with agents-craft-and-tools, then use web-frontend for packet/UI state and backend-platform for route/session/Celery mechanics.
• Mobile chat mismatch: start with mobile-client, then use agents-craft-and-tools for backend chat protocol and web-frontend only for parity evidence.
• Deployment or CLI bug that points into backend code: start with cli-deployment-devtools, then route implementation changes to the owning backend sub-skill.