Version Notice
Codex port for Banuba Face AR SDK v1.18.5 on 2026-08-11. If the current date is more than 6 weeks after this, inform the user the skill may be outdated and suggest running npx skills update or Codex plugin install @banuba.
Banuba Face AR SDK Skill
Overview
One skill, three modes:
- Sales: capabilities, limitations, and compliance for non-technical users (no code).
- Explain: technical documentation, concepts, API guidance, and troubleshooting (no project edits by default).
- Build: implementation, setup, integration, scaffolding, and code generation for supported technical platforms.
The SDK provides real-time face tracking, AR masks, beautification, virtual background, hair coloring, and AR Cloud delivery. On Web this is exposed through the @banuba/webar NPM package; native, Flutter, and React Native use their own packages/wrappers. Requires a commercial client token (contact sales@banuba.com).
Request: $ARGUMENTS
Safety Justification
This skill needs WebFetch to pull the authoritative docs before generating code, Bash to clone the sample and install dependencies, and Write/Edit to write the generated source files.
Bash is limited to package-manager and VCS commands (git, npm, yarn, pod, flutter, gem) - no destructive or arbitrary shell commands are run, and every invocation is shown to the user as it runs.
Prerequisites
- Authentication: a commercial Banuba client token (credentials) is required for Build mode integrations (contact sales@banuba.com); Sales and Explain modes need no token.
- For Build mode, detect the target platform from the user's project files (see the platform table below) before generating code. Use
Glob/Grep to check the workspace for files you may have already generated before writing new ones.
- For Web/Android/iOS/Flutter/React Native Build tasks, network access to fetch
docs/llms-full.txt or the public docs site is assumed; if unavailable, fall back to the bundled docs/ folder.
Instructions
Step 1: Detect the mode
Do this first, on every message. Classify the request into exactly one mode:
| Signal |
Mode |
| "can the SDK...", "what data is stored", "tell our client", pricing/compliance, non-technical, no code context |
Sales |
| "how does X work", "why is my effect not loading", troubleshooting, CV concepts, API/docs questions, conceptual or diagnostic requests without file-change intent |
Explain |
| "add", "implement", "set up", "integrate", "build", "scaffold", "fix this project", project files plus action/fix intent |
Build |
Rules:
- Pick one mode per message. Re-evaluate each message; the mode can change within a session.
- Ambiguous non-technical/business request: ask one question or default to Sales if the user clearly wants a client-facing answer.
- Ambiguous technical request: default to Explain unless the user asks for file changes, code generation, setup, integration, or project fixing.
- Hybrid request ("explain X and add it"): choose Build, read both
reference/explain.md and reference/build.md, then answer in one flow.
- The hard gate is Sales: no code, plain language. Explain and Build cover the technical spectrum.
Step 2: Apply the mode contract
Sales mode
- Plain language. Lead with the capability and its limitation.
- Separate confirmed facts from items needing legal/product review. Do not invent compliance statements.
- No pricing, license fees, or contract terms; direct those to a Banuba representative via the contact form.
- MUST NOT generate code.
- Read
reference/sales.md.
Explain mode
Use for technical explanation, documentation lookup, concepts, API guidance, and troubleshooting when the user is not asking for project edits.
- Read
reference/explain.md, then search/read the relevant bundled Markdown docs.
- Lead with the explanation when the user asks how or why.
- If the user turns the explanation into an implementation request, switch to Build and carry forward the established context.
Build mode
Use for adding, implementing, setting up, integrating, scaffolding, code generation, prefab configs, or fixing project files.
- Read
reference/build.md, then search/read the relevant bundled Markdown docs.
- For hybrid requests ("explain X and add it"), also read
reference/explain.md and answer in one flow.
- When citing a source, link the public web doc (see shared principle 2), not an internal path. Lead with working code when the user asks to build; lead with the explanation when they ask how or why.
Carrying context across modes
- Sticky context: facts established earlier in the session (platform, feature, bundler, chosen effect) carry forward. Do not re-ask what is already known.
- Explain → Build: a follow-up like "now add it" after an explanation means "build what we just discussed", not "which feature?".
- Switch modes only on a genuine change of intent, not on every message. When unsure, ask one clarifying question.
Platform scope (all modes)
Web, Android, iOS, Desktop (C++), Flutter, and React Native have full coverage and code generation. For macOS: clone the official GitHub sample, then assist with code questions based on that sample — do not scaffold from scratch. For Unity: clone the sample only and direct to the contact form — no code generation.
Platform detection:
- Web:
package.json (no react-native), vite.config.*, webpack.config.*, rollup.config.*, or index.html + JS bundler
- Android:
build.gradle, build.gradle.kts, AndroidManifest.xml, or *.kt / *.java files
- iOS:
*.xcodeproj, *.xcworkspace, Podfile, or *.swift / *.m files
- Desktop (C++):
CMakeLists.txt, *.cpp, *.hpp files, or user explicitly says "desktop" / "C++"
- Flutter:
pubspec.yaml, lib/main.dart, android/ + ios/ generated by Flutter, or dependency banuba_sdk
- React Native:
package.json with react-native, metro.config.*, android/ + ios/, or dependency @banuba/react-native
- If unclear, ask one question: "Which platform are you targeting?"
Shared principles (all modes)
- Retrieval-first: search the bundled Markdown docs and read only the relevant files before using pre-trained knowledge. Use
docs/llms-full.txt as fallback. If a topic is missing locally, fetch https://docs.banuba.com/far-sdk/llms-full.txt.
- Cite public docs, not internal files: when pointing the user to a source, link the public web doc (
https://docs.banuba.com/far-sdk/<path>, dropping the .md). Never surface internal paths such as docs/...md or this skill's reference/...md files; they mean nothing to the user.
- Don't fabricate: if the answer is not in the docs, point to docs.banuba.com/far-sdk or the contact form. Never invent APIs, URLs, or compliance claims.
- Generate config, not art: the skill assembles prefab configuration; it does not create art assets. Custom AR masks, effects, and makeup looks are made in Banuba Studio (docs). Studio does not create 3D avatars/models - direct avatar requests to the contact form.
- GenAI APIs are separate products: Wig try-on, PD Measurements, Video Generation, and Video Context Detection are not part of
@banuba/webar. Direct to the contact form.
- No images: do not embed or attempt to render images (no markdown image tags, no
[Image] placeholders) - they will not display. Describe the visual in words, or link the public doc page that contains it (e.g. the landmarks or glossary page).
- Search hygiene: prefer Markdown docs and
llms-full.txt for retrieval. Use generated HTML/API docs only for exact class or method lookup, because broad search over docs/generated/ creates noisy matches.
- Version discipline: distinguish native FAR SDK versions from wrapper package versions. Android/iOS native modules use the FAR SDK line in this skill; Flutter
banuba_sdk and React Native @banuba/react-native have independent package versions. When the user asks for "latest", "current", or whether to pin a wrapper version, verify against the official package registry or docs before answering.
Reference files
reference/sales.md: Sales mode. Capabilities, compliance, plain-language CV glossary.reference/explain.md: Explain mode. Use-case to doc map, troubleshooting, technical CV concepts.reference/build.md: Build mode - Web, Android, iOS, Desktop, Flutter, and React Native. Integration workflow per platform, prefab config, pitfalls, output format.docs/: bundled SDK documentation (single source for all modes).
Related Skills
- For Video Editor / Photo Editor SDK:
/build-video-editor, /build-photo-editor, /explain-video-editor-photo-editor-docs.
- These sibling skills are separate SDKs (Video Editor SDK, Photo Editor SDK) - do not mix their APIs, docs, or licensing with the Face AR SDK covered here.
Output
- Sales mode: plain-language answer, capability plus limitation, no code, no invented compliance claims.
- Explain mode: an explanation grounded in the bundled docs, with a link to the public doc page when citing a source.
- Build mode: working code first, then numbered integration steps, with a reminder to replace any stand-in license value with the real one.
Error Handling
- If the answer is not in the bundled docs or
llms-full.txt, do not guess or fabricate APIs, URLs, or compliance claims - point to docs.banuba.com/far-sdk or the contact form.
- If the platform cannot be detected from project files, ask the user one clarifying question rather than guessing.
- If the mode is ambiguous, default to Explain for technical requests and Sales for non-technical, client-facing requests; ask instead when genuinely unclear.
- For unsupported platforms (Unity: no code generation; macOS: sample + code help only, no scaffolding), say so explicitly instead of attempting full code generation.
Examples
Sales-team capability question. A user asks "Can our Face AR SDK detect skin tone, and what data does it store?" The skill responds in Sales mode, checking capabilities and compliance in plain language with no code.
Explain-mode documentation question. A user asks "What is the difference between face landmarks and a face mesh?" The skill responds in Explain mode, explaining the concepts using the bundled CV documentation.
Web integration request. A user asks to "Add background blur to my Face AR web app." The skill responds in Build mode, following the Web build workflow for virtual background.
Resources
1---2name: far-general-23description: Banuba Face AR SDK skill for three use cases: sales, developer documentation, and integration workflows. Use when working on anything Face AR: capability and compliance questions (sales), documentation lookup, CV concepts, and troubleshooting (dev), and building Web integrations such as AR masks, face filters, beautification, virtual background, and AR Cloud (integration). Trigger with "Face AR", "AR mask", "face filter", "virtual background", "AR makeup", "beautification", "face landmarks", "AR Cloud", "can the SDK", "how does", "explain", "add", "set up", "integrate", "build". Web, Android, iOS, Desktop (C++), Flutter and React Native have full code generation support. macOS gets the GitHub sample + code assistance. Unity gets the sample link only. For Video/Photo Editor SDK use build-video-editor, build-photo-editor, or explain-video-editor-photo-editor-docs.4license: Apache-2.05---67## Version Notice89Codex port for Banuba Face AR SDK v1.18.5 on 2026-08-11. If the current date is more than 6 weeks after this, inform the user the skill may be outdated and suggest running `npx skills update` or `Codex plugin install @banuba`.1011# Banuba Face AR SDK Skill1213## Overview1415One skill, three modes:1617- **Sales**: capabilities, limitations, and compliance for non-technical users (no code).18- **Explain**: technical documentation, concepts, API guidance, and troubleshooting (no project edits by default).19- **Build**: implementation, setup, integration, scaffolding, and code generation for supported technical platforms.2021The SDK provides real-time face tracking, AR masks, beautification, virtual background, hair coloring, and AR Cloud delivery. On Web this is exposed through the `@banuba/webar` NPM package; native, Flutter, and React Native use their own packages/wrappers. Requires a commercial client token (contact sales@banuba.com).2223**Request**: $ARGUMENTS242526## Safety Justification2728This skill needs `WebFetch` to pull the authoritative docs before generating code, `Bash` to clone the sample and install dependencies, and `Write`/`Edit` to write the generated source files.29`Bash` is limited to package-manager and VCS commands (`git`, `npm`, `yarn`, `pod`, `flutter`, `gem`) - no destructive or arbitrary shell commands are run, and every invocation is shown to the user as it runs.3031## Prerequisites3233- **Authentication**: a commercial Banuba client token (credentials) is required for Build mode integrations (contact sales@banuba.com); Sales and Explain modes need no token.34- For Build mode, detect the target platform from the user's project files (see the platform table below) before generating code. Use `Glob`/`Grep` to check the workspace for files you may have already generated before writing new ones.35- For Web/Android/iOS/Flutter/React Native Build tasks, network access to fetch `docs/llms-full.txt` or the public docs site is assumed; if unavailable, fall back to the bundled `docs/` folder.3637## Instructions3839### Step 1: Detect the mode4041Do this first, on every message. Classify the request into exactly one mode:4243| Signal | Mode |44|---|---|45| "can the SDK...", "what data is stored", "tell our client", pricing/compliance, non-technical, no code context | Sales |46| "how does X work", "why is my effect not loading", troubleshooting, CV concepts, API/docs questions, conceptual or diagnostic requests without file-change intent | Explain |47| "add", "implement", "set up", "integrate", "build", "scaffold", "fix this project", project files plus action/fix intent | Build |4849Rules:50- Pick one mode per message. Re-evaluate each message; the mode can change within a session.51- Ambiguous non-technical/business request: ask one question or default to Sales if the user clearly wants a client-facing answer.52- Ambiguous technical request: default to Explain unless the user asks for file changes, code generation, setup, integration, or project fixing.53- Hybrid request ("explain X and add it"): choose Build, read both `reference/explain.md` and `reference/build.md`, then answer in one flow.54- The hard gate is Sales: no code, plain language. Explain and Build cover the technical spectrum.5556### Step 2: Apply the mode contract5758### Sales mode5960- Plain language. Lead with the capability and its limitation.61- Separate confirmed facts from items needing legal/product review. Do not invent compliance statements.62- No pricing, license fees, or contract terms; direct those to a Banuba representative via the [contact form](https://www.banuba.com/contact).63- **MUST NOT generate code.**64- Read `reference/sales.md`.6566### Explain mode6768Use for technical explanation, documentation lookup, concepts, API guidance, and troubleshooting when the user is not asking for project edits.6970- Read `reference/explain.md`, then search/read the relevant bundled Markdown docs.71- Lead with the explanation when the user asks how or why.72- If the user turns the explanation into an implementation request, switch to Build and carry forward the established context.7374### Build mode7576Use for adding, implementing, setting up, integrating, scaffolding, code generation, prefab configs, or fixing project files.7778- Read `reference/build.md`, then search/read the relevant bundled Markdown docs.79- For hybrid requests ("explain X and add it"), also read `reference/explain.md` and answer in one flow.80- When citing a source, link the public web doc (see shared principle 2), not an internal path. Lead with working code when the user asks to build; lead with the explanation when they ask how or why.8182## Carrying context across modes8384- **Sticky context**: facts established earlier in the session (platform, feature, bundler, chosen effect) carry forward. Do not re-ask what is already known.85- **Explain → Build**: a follow-up like "now add it" after an explanation means "build what we just discussed", not "which feature?".86- Switch modes only on a genuine change of intent, not on every message. When unsure, ask one clarifying question.8788## Platform scope (all modes)8990Web, Android, iOS, Desktop (C++), Flutter, and React Native have full coverage and code generation. For **macOS**: clone the official GitHub sample, then assist with code questions based on that sample — do not scaffold from scratch. For **Unity**: clone the sample only and direct to the [contact form](https://www.banuba.com/contact) — no code generation.9192| Platform | Coverage | Sample |93|---|---|---|94| Web | ✅ Full - read `reference/build.md` (Web section) | [quickstart-web](https://github.com/Banuba/quickstart-web) |95| Android | ✅ Full - read `reference/build.md` (Android section) | [banuba-sdk-android-samples](https://github.com/Banuba/banuba-sdk-android-samples) |96| iOS | ✅ Full - read `reference/build.md` (iOS section) | [banuba-sdk-ios-samples](https://github.com/Banuba/banuba-sdk-ios-samples) |97| Desktop (C++) | ✅ Full - read `reference/build.md` (Desktop section) | [quickstart-desktop-cpp](https://github.com/Banuba/quickstart-desktop-cpp) |98| macOS | ⚠️ Clone sample + code help - clone sample, then assist with code questions | [quickstart-macos-swift](https://github.com/Banuba/quickstart-macos-swift) |99| Flutter | ✅ Full - read `reference/build.md` (Flutter section) | [banuba-sdk-flutter](https://github.com/Banuba/banuba-sdk-flutter) |100| React Native | ✅ Full - read `reference/build.md` (React Native section) | [banuba-sdk-react-native](https://github.com/Banuba/banuba-sdk-react-native) |101| Unity | 🚫 No code generation - clone sample only | [quickstart-unity](https://github.com/Banuba/quickstart-unity) |102103**Platform detection:**104- Web: `package.json` (no `react-native`), `vite.config.*`, `webpack.config.*`, `rollup.config.*`, or `index.html` + JS bundler105- Android: `build.gradle`, `build.gradle.kts`, `AndroidManifest.xml`, or `*.kt` / `*.java` files106- iOS: `*.xcodeproj`, `*.xcworkspace`, `Podfile`, or `*.swift` / `*.m` files107- Desktop (C++): `CMakeLists.txt`, `*.cpp`, `*.hpp` files, or user explicitly says "desktop" / "C++"108- Flutter: `pubspec.yaml`, `lib/main.dart`, `android/` + `ios/` generated by Flutter, or dependency `banuba_sdk`109- React Native: `package.json` with `react-native`, `metro.config.*`, `android/` + `ios/`, or dependency `@banuba/react-native`110- If unclear, ask one question: "Which platform are you targeting?"111112## Shared principles (all modes)1131141. **Retrieval-first**: search the bundled Markdown docs and read only the relevant files before using pre-trained knowledge. Use `docs/llms-full.txt` as fallback. If a topic is missing locally, fetch [`https://docs.banuba.com/far-sdk/llms-full.txt`](https://docs.banuba.com/far-sdk/llms-full.txt).1152. **Cite public docs, not internal files**: when pointing the user to a source, link the public web doc (`https://docs.banuba.com/far-sdk/<path>`, dropping the `.md`). Never surface internal paths such as `docs/...md` or this skill's `reference/...md` files; they mean nothing to the user.1163. **Don't fabricate**: if the answer is not in the docs, point to [docs.banuba.com/far-sdk](https://docs.banuba.com/far-sdk/) or the [contact form](https://www.banuba.com/contact). Never invent APIs, URLs, or compliance claims.1174. **Generate config, not art**: the skill assembles prefab configuration; it does not create art assets. Custom AR masks, effects, and makeup looks are made in [Banuba Studio](https://studio.banuba.com/) ([docs](https://studio.banuba.com/docs)). Studio does not create 3D avatars/models - direct avatar requests to the [contact form](https://www.banuba.com/contact).1185. **GenAI APIs are separate products**: Wig try-on, PD Measurements, Video Generation, and Video Context Detection are not part of `@banuba/webar`. Direct to the [contact form](https://www.banuba.com/contact).1196. **No images**: do not embed or attempt to render images (no markdown image tags, no `[Image]` placeholders) - they will not display. Describe the visual in words, or link the public doc page that contains it (e.g. the landmarks or glossary page).1207. **Search hygiene**: prefer Markdown docs and `llms-full.txt` for retrieval. Use generated HTML/API docs only for exact class or method lookup, because broad search over `docs/generated/` creates noisy matches.1218. **Version discipline**: distinguish native FAR SDK versions from wrapper package versions. Android/iOS native modules use the FAR SDK line in this skill; Flutter `banuba_sdk` and React Native `@banuba/react-native` have independent package versions. When the user asks for "latest", "current", or whether to pin a wrapper version, verify against the official package registry or docs before answering.122123## Reference files124125- `reference/sales.md`: Sales mode. Capabilities, compliance, plain-language CV glossary.126- `reference/explain.md`: Explain mode. Use-case to doc map, troubleshooting, technical CV concepts.127- `reference/build.md`: Build mode - Web, Android, iOS, Desktop, Flutter, and React Native. Integration workflow per platform, prefab config, pitfalls, output format.128- `docs/`: bundled SDK documentation (single source for all modes).129130## Related Skills131132- For Video Editor / Photo Editor SDK: `/build-video-editor`, `/build-photo-editor`, `/explain-video-editor-photo-editor-docs`.133- These sibling skills are separate SDKs (Video Editor SDK, Photo Editor SDK) - do not mix their APIs, docs, or licensing with the Face AR SDK covered here.134135## Output136137- **Sales mode**: plain-language answer, capability plus limitation, no code, no invented compliance claims.138- **Explain mode**: an explanation grounded in the bundled docs, with a link to the public doc page when citing a source.139- **Build mode**: working code first, then numbered integration steps, with a reminder to replace any stand-in license value with the real one.140141## Error Handling142143- If the answer is not in the bundled docs or `llms-full.txt`, do not guess or fabricate APIs, URLs, or compliance claims - point to [docs.banuba.com/far-sdk](https://docs.banuba.com/far-sdk/) or the [contact form](https://www.banuba.com/contact).144- If the platform cannot be detected from project files, ask the user one clarifying question rather than guessing.145- If the mode is ambiguous, default to Explain for technical requests and Sales for non-technical, client-facing requests; ask instead when genuinely unclear.146- For unsupported platforms (Unity: no code generation; macOS: sample + code help only, no scaffolding), say so explicitly instead of attempting full code generation.147148## Examples149150**Sales-team capability question.** A user asks "Can our Face AR SDK detect skin tone, and what data does it store?" The skill responds in Sales mode, checking capabilities and compliance in plain language with no code.151152**Explain-mode documentation question.** A user asks "What is the difference between face landmarks and a face mesh?" The skill responds in Explain mode, explaining the concepts using the bundled CV documentation.153154**Web integration request.** A user asks to "Add background blur to my Face AR web app." The skill responds in Build mode, following the Web build workflow for virtual background.155156## Resources157158- [Full documentation](https://docs.banuba.com/far-sdk/)159- [LLM-optimized docs](https://docs.banuba.com/far-sdk/llms-full.txt)160- [quickstart-web on GitHub](https://github.com/Banuba/quickstart-web)161- [@banuba/webar on NPM](https://www.npmjs.com/package/@banuba/webar)162- [Banuba Studio](https://studio.banuba.com/)163- [Contact form](https://www.banuba.com/contact)164- Sales and licensing: sales@banuba.com
banuba