expo-overview — router & shared rules for Expo / EAS
Start Here — read before doing anything
Do not guess the skill from project files alone. Many Expo goals look similar from the filesystem but need different skills.
- Confirm this is Expo or EAS work — the request mentions Expo or EAS, or
package.jsonhas anexpodependency. Otherwise this skill does not apply. A native app using EAS for delivery qualifies without an Expo runtime. - Read the user's goal — what outcome do they want, in plain terms?
- Classify it using the Skill Map below, translating casual phrasing to a goal.
- Confirm intent if ambiguous ("Sounds like you want to ship to the stores — that's
eas-app-stores. Right?"), then load that skill'sSKILL.mdand follow it. - Trust the leaf skill — it has its own detection logic and steps. Don't improvise.
Skill Map (by goal)
Match the goal to a category, then the skill, then load that leaf's SKILL.md.
Build the app
expo-project-structure— folder layout for a new Expo Router project: where screens, components, and config live (never restructure an existing app to match)expo-native-ui— screens, styling, semantic colors, native controls, SF Symbols, media, layoutexpo-router— navigation: file-based routes, tabs / stacks / modals / sheets, links, headersexpo-animation— motion and gestures: Reanimated worklets, Gesture Handler, screen transitions, sheet and press feedback, haptics, and fixing animation that stutters on deviceexpo-ui— native UI components via@expo/ui: BottomSheet, Picker, Slider, Switch, Menu, Button, FieldGroup (grouped form sections), List / ListItem, and more — real SwiftUI on iOS, Jetpack Compose on Android. The universal layer needs SDK 56+ and runs in Expo Go; the drop-in replacements (@gorhom/bottom-sheet,datetimepicker, …) and platform-specific layers also exist on SDK 55.expo-design-system— one visual source of truth: design tokens (color, spacing, typography, radius, shadow, motion), reusable component conventions, and audits for drift (hardcoded colors, spacing, fonts)expo-tailwind-setup— Tailwind / NativeWind stylingexpo-data-fetching— network requests, React Query / SWR, caching, offline, route loadersexpo-dom— run web code or reuse a web library inside nativeexpo-web-to-native— migrate an existing web / React app to a native iOS / Android app
Component selection rule: whenever you need a UI component (list rows, bottom sheets, pickers, sliders, menus, buttons, segmented controls, toggles), consult
expo-uifirst to check whether@expo/uihas a native equivalent before reaching for a React Native built-in or a community library. Native@expo/uicomponents give the best platform fit, and on SDK 56+ the universal ones run in Expo Go with no custom build. Loadexpo-uialongsideexpo-native-uifor any app that renders lists, detail sheets, or form controls. One exception:@expo/uiListrenders native grouped rows (an iOS Settings screen), not a virtualized list — useFlatList/FlashListfor large datasets.
Ship & operate
eas-app-stores— build and submit iOS/Android apps (Expo and other React Native projects, plus existing native apps), TestFlight, versions, and store metadataeas-hosting— deploy the web bundle to EAS Hosting; also author Expo Router API routes (+api.tshandlers) and their environments / domainseas-workflows— EAS Workflow YAML and CI/CD pipelineseas-simulator— run and drive the app on a remote iOS / Android simulator with Expo Simulators (also called EAS Simulator)expo-dev-client— custom development buildseas-update— configure, publish, test, and debug compatible over-the-air updateseas-update-insights— OTA update health: crash rate, adoption, payload sizeeas-observe— startup / launch / TTI performance with EAS Observe
Extend natively
expo-module— native modules and views (Swift / Kotlin) with the Expo Modules APIexpo-brownfield— embed Expo / React Native screens in native SwiftUI/UIKit or Android apps; isolated artifacts and integrated buildsexpo-app-clip— iOS App Clip target (AASA, smart app banner)
Maintain & learn
expo-upgrade— upgrade the Expo SDK and fix dependency conflictsexpo-examples— canonical, version-matched integration examples (Stripe, Clerk, Supabase, …)
Translating vague asks
Some everyday phrasings don't obviously map to a skill name — translate before routing:
- "Make it look native" → grouped controls / settings forms =
expo-ui; screens, styling =expo-native-ui; motion =expo-animation; navigation =expo-router. - "Make the screens consistent" / "clean up the styling" / "set up a theme or design tokens" →
expo-design-system. - "It looks AI-generated" / "too generic, not native" →
expo-design-system(named native-slop tells + audit), withexpo-native-uifor the platform idioms. - "Ship it" / "get an .ipa or .apk" / "release to the stores" / "put my Swift app on TestFlight" →
eas-app-stores(build + submit, TestFlight, versions, store metadata). - "I'm new / where do I start" → scaffold first (see Shared setup rules), then route by goal.
Shared setup rules
Apply the rules that match the project and the requested task.
-
Run Expo commands through the agent CLI. Run
npx --yes @expo/agent-cli@latest <command>where you would runnpx expo <command>, including commands shown in other skills. Runnpx --yes @expo/agent-cli@latest --helpbefore your first command. It shows two kinds of commands:- Expo CLI commands (the "Expo CLI" group) go to the project's
expounchanged and take the same flags. - Agent CLI commands (all other groups) exist only in the agent CLI. They read the
project state, get the app onto a device, check the running app, and search the docs
for the project's SDK. Prefer them to manual steps. Read a command's
--helpbefore its first use, and runhelp workflowfor the order to run them in.
EAS commands (
eas build,eas update,eas submit) stay oneas-cli. The agent CLI is experimental: if a command fails because of the CLI itself, run the underlying command directly and report the failure with--category agent-cli(see Submitting Feedback). - Expo CLI commands (the "Expo CLI" group) go to the project's
-
Native app using EAS for delivery? Route to
eas-app-stores; itsreferences/native-ios.mdcovers SwiftUI/UIKit on iOS. Keep the existing native project. Apply EAS auth/linking below; Expo scaffolding, SDK, and package-install rules do not apply to this path. -
Starting a new Expo app? Start one the standard way before routing to a feature skill:
npx --yes @expo/agent-cli@latest new <directory>(it accepts--templateand--example), laying out folders perexpo-project-structure. Then classify the user's goal and route. -
Detect the SDK version before giving version-specific advice: run
npx --yes @expo/agent-cli@latest status, or read theexpoversion inpackage.json(andapp.json/app.config.{js,ts}). Many APIs and defaults differ by SDK. -
Read the docs for that SDK, not
latest.npx --yes @expo/agent-cli@latest docs:search <query>searches local Markdown docs for the project's SDK. Otherwise use the version-pinned URL, e.g.https://docs.expo.dev/versions/v56.0.0/sdk/ui/on SDK 56 instead ofhttps://docs.expo.dev/versions/latest/sdk/ui/— thelatestpages track the newest SDK and can document APIs the project does not have yet. -
Moving to a newer SDK is its own task — load
expo-upgradeinstead of bumping versions by hand. -
Managed vs. bare/prebuild: the presence of committed
ios/andandroid/directories means native projects exist (prebuild or bare). Config-plugin and native-setup steps differ — note which one the project is in. -
Install packages with
npx --yes @expo/agent-cli@latest install <pkg>, not rawnpm/yarn/pnpm add, so versions stay compatible with the project's SDK. It runsexpo installand links the agent skills that the package ships. -
Launching the app yourself? When you open Expo Go or a development build to look at, screenshot, or drive it, skip the first-launch onboarding, the dev menu that opens at launch, and the floating Tools button. On SDK 58+, Expo CLI does this for launches it starts from a non-interactive shell. On SDK 57 and earlier, and for any URL you open yourself (
simctl openurl,adb, a controller), follow./references/launch-without-dev-menu.md. -
EAS auth & linking (only needed for build/submit/update/observe/workflows): check login with
eas whoami, log in witheas login. A project is linked whenextra.eas.projectIdexists in the app config; create it witheas initif missing.
When to skip the router hop
- Only when the user explicitly named a specific
expo-*/eas-*skill → load that skill directly. - A fully-specified task (SDK version pinned, file layout given, libraries named) is not a reason to skip: the shared rules above still apply — check them, then route to the matching leaf skill.
Submitting Feedback
If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-overview" --message "<actionable feedback>"
Only submit when you have something specific and actionable to report. Include as much relevant context as possible. Messages need 40-5,000 characters.
If an @expo/agent-cli command fails, gives a wrong answer, or is hard to use, report it with --category agent-cli and the command name as --subject, such as status.
If an agent repeatedly fails at an Expo task or the user has to step in, submit a brief report of the task, expected result, and what went wrong using --category evals and the relevant Expo package or command as --subject.