Voltra Agent Skill

Voltra

Use this as the single Voltra skill entrypoint. Keep all product-wide ground truth here and load references from references/ as needed.

Voltra-Wide Ground Truth

• Never generate native platform UI code for Voltra tasks. Use Voltra JSX and Voltra JS APIs.
• Do not generate Swift, Kotlin, Java, Objective-C, or platform XML unless the user explicitly asks to edit an existing Voltra-supported Android widget preview XML file.
• Always solve Voltra tasks through Voltra JavaScript or TypeScript APIs, JSX components, and the Expo config plugin first.
• If a task appears to require native code, first check whether Voltra already exposes a JS API or config option. Prefer that path.
• Do not scaffold native extension code manually. Voltra's config plugin owns native target setup.
• Do not use plain React Native primitives inside Voltra-rendered trees. Avoid View, Text, Pressable, TouchableOpacity, and similar RN UI primitives for Live Activity or Android widget content.
• For iOS app code, import Voltra from @use-voltra/ios and runtime APIs from @use-voltra/ios-client.
• For Android app code, import VoltraAndroid from @use-voltra/android and runtime APIs from @use-voltra/android-client.
• Keep iOS and Android authoring paths separate unless the user explicitly asks for a shared abstraction.
• Update config before writing registration-dependent UI code.
• Treat images as a Voltra concern, not a native-code concern. Prefer Voltra image props, Voltra asset directories, and Voltra preloading APIs.
• When guidance conflicts, prefer this skill's internal references first, then hosted docs on use-voltra.dev.
• Use hosted docs on https://use-voltra.dev when deeper documentation is needed.

Reference Routing

Read only the references needed for the current task:

• Setup, install, Expo Dev Client, expo prebuild: references/setup.md
• React Native CLI projects and voltra apply: references/react-native-cli.md
• app.json, app.config.*, plugin keys, widget registration, groupIdentifier, enablePushNotifications: references/app-config.md
• Exact plugin fields and widget registration schema: references/plugin-schema.md
• iOS Live Activities, Dynamic Island, lock screen variants, supplemental activity families: references/ios-live-activities.md
• Exact Live Activity variant shapes: references/variant-shapes.md
• iOS Home Screen widgets, accessory widgets, scheduled widgets, widget timelines, widget families, VoltraWidgetPreview, updateWidget, scheduleWidget, reloadWidgets, getActiveWidgets: references/ios-widgets.md
• Exact iOS widget families and fallback behavior: references/widget-families.md
• Charts for iOS widgets, Live Activities, and Android widgets: references/charts.md
• Android widgets, Android widget previews, pre-rendering, widget updates: references/android-widgets.md
• Android ongoing notifications, notification channels, and background-task updates: references/android-ongoing-notifications.md
• Server-driven widgets, serverUpdate, widget polling flows, createWidgetUpdateHandler, setWidgetServerCredentials, clearWidgetServerCredentials: references/server-driven-widgets.md
• Android component choices and widget API checklist: references/component-mapping.md, references/runtime-api-checklist.md
• APNS, push tokens, push-to-start, channel IDs, server-rendered Live Activity payloads: references/ios-server-updates.md and usually references/ios-live-activities.md
• Exact APNS flow details: references/push-flow.md
• Image handling for Voltra surfaces: references/images.md plus the target surface reference

Working Style

• Identify the target platform and surface first.
• Confirm the correct Voltra namespace and JS entrypoint.
• If the task involves charts, verify the public JSX props and platform behavior before writing code or docs.
• Update config before writing registration-dependent UI code.
• Read only the domain references needed for the task.
• Use Voltra APIs that already exist in the repo before inventing new abstractions.
• Keep answers scoped to the requested platform.

Reference Index

• references/source-of-truth.md
• references/images.md
• references/setup.md
• references/react-native-cli.md
• references/app-config.md
• references/plugin-schema.md
• references/ios-live-activities.md
• references/variant-shapes.md
• references/ios-widgets.md
• references/widget-families.md
• references/charts.md
• references/android-widgets.md
• references/android-ongoing-notifications.md
• references/server-driven-widgets.md
• references/component-mapping.md
• references/runtime-api-checklist.md
• references/ios-server-updates.md
• references/push-flow.md