voltra

Builds the small pieces of an app that live outside the app — home-screen widgets, the live panel on an iPhone's lock screen, ongoing notifications — in JavaScript, so nobody has to write Swift or Kotlin to get them shipped.

WHEN TO USE

SCOPE

USE FOR

Build or debug an iOS Live Activity or Dynamic Island interface using Voltra's components.
Set up an iOS or Android home-screen widget, including scheduled widget updates.
Add an ongoing Android notification driven by background-task updates.
Wire up server-driven widget updates, or use Apple's push notifications to start a Live Activity remotely.
Add a chart to an iOS widget, a Live Activity, or an Android widget.
Configure app.json, or the Expo config plugin, to register a Voltra widget.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (5)

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

Local tool required

1 FOR YOU

01
Install the Voltra packages and CLI in your app
Building Voltra widgets or Live Activities means installing the @use-voltra packages and Voltra's Expo config plugin (or running voltra apply for bare RN CLI) in your React Native/Expo project — covered in the bundled setup reference — before any Voltra JSX or API works.

Listed as free: Connected services may require an account or charge fees.
Installation: One command — usually under 2 minutes.

Not standalone. This skill ships with callstackincubator/voltra and only works together with that tool — install the tool first, then add this skill.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add callstackincubator/voltra --skill "voltra" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub