zepp-os-skills

Use when controlling the Zepp OS app itself — requesting/querying runtime permissions, reading package info, detecting the scene (normal/AOD), accessing live workout/sport data, adding a text keyboard, or building a Workout Extension or media app.

Use when running Zepp OS code in the background or scheduling something for later - an app-service that runs independently of the foreground page (@zos/app-service, for tallying activity all day, etc.), waking the app at a wall-clock time or recurring schedule (@zos/alarm, "wake up at 8am every morning"), running a callback every N ms even when the screen is off (@zos/timer createSysTimer), posting a notification to the watch notification center (@zos/notification, "push a notification when the timer finishes"), or reacting to system events like sleep / shutdown / wake (app-event module). Use even when the wording is generic ("run later", "send a notification", "schedule a one-off task in 10 minutes", "run all day in the background") - this is the right skill for any deferred or background execution on the watch. Do not use for sending data from the phone side service to the watch (zepp-os-communication).

Use when improving the quality of a Zepp OS project itself rather than implementing a feature - debugging a Zepp OS app (there are no breakpoints, so logging strategy per runtime), catching otherwise-silent lifecycle errors (errors in onInit / build / onDestroy are swallowed with no source map), wrapping lifecycle hooks so a crash actually surfaces, structuring src/ for readability and unit testing, localizing strings via .po / gettext / i18n, or migrating a legacy 1.0 hm* / hmSensor / hmUI app to the modern @zos/* API. Use even when the question sounds like a generic JS / architecture / testing / i18n question if the context is Zepp OS. Do not use for the implementation itself of a feature - use the topic-specific skill (zepp-os-sensors for sensor reads, zepp-os-ui for widgets, etc.).

Use when sending data between a Zepp OS device app and its phone side service, making HTTP/fetch requests, downloading or transferring files to the watch, or talking to external BLE peripherals.

Use when handling watch-side hardware input or system info in a Zepp OS device app - reading physical buttons or digital crown, detecting wrist-raise / wrist-motion / gestures, showing a toast or a modal / confirm dialog, reading screen shape or device info, reading the user's system preferences (12h/24h time format, units, language, mode), loading i18n .po files, referencing asset image paths, or using EventBus / log / assets / px helpers and stringToBuffer / bufferToString (string ↔ ArrayBuffer). Use even when the task sounds generic ("show a confirm dialog", "read the language setting", "convert a string to a buffer") - Zepp OS has its own @zos/interaction, @zos/settings, @zos/device, @zos/i18n, @zos/utils APIs. Do not use for sensor / health data (zepp-os-sensors), page navigation (zepp-os-navigation-lifecycle), persistent storage (zepp-os-settings-storage), drawing UI widgets (zepp-os-ui), watchface rendering (zepp-os-watchface), or declaring permissions in app.json (zepp-os-fundamentals).

Use for Zepp OS project setup and structure decisions - editing app.json (manifest, permissions list, module entries, API_LEVEL, targets, designWidth, assets), deciding where code belongs (device app vs side service vs settings app vs app-service vs watchface module), supporting round + square device targets, scaffolding or laying out a new Mini Program or Watchface project, or explaining the four runtime contexts. Use whenever the question is "where does this code go", "what goes in app.json", "what permission do I declare in app.json", "how do I target this device", "how is a watchface project laid out vs a regular app", or "what's the difference between the device app and the side service". Do not use for runtime permission requests at execution time (zepp-os-app-control), for the implementation inside a specific module (use the topic skill), or for zeus CLI commands (zeus-cli).

Use when navigating between Zepp OS device-app pages, passing data between pages, wiring App()/Page() lifecycle hooks, launching or exiting the app, or controlling page scroll/swipe.

Use when the primary Zepp OS task is directly reading, subscribing to, configuring, or stopping @zos/sensor sensor/health data on a device app - heart rate, steps, calories, blood oxygen, accelerometer, gyroscope, GPS/geolocation, sleep, stress, battery, compass, workout, weather, wear/screen state. Use for permission details only when paired with implementing sensor reads. Do not use only because a query mentions sensor data if the task is persisting or aggregating values across app restarts, sending data to phone, displaying it in UI, declaring app.json permission strings, requesting permissions, scheduling background work, or building a watchface complication.

Use when persisting data or building settings in a Zepp OS project - saving / loading user preferences or app data so they survive app restart, storing flags like "onboarding completed" or accumulated step / sensor / health totals, building the companion Settings App that runs inside the Zepp phone app (AppSettingsPage with Toggle / Select / Section / Slider components), syncing a value the user picks in the phone Settings UI down to the watch via settingsStorage, or using @zos/storage LocalStorage / @zos/fs on the watch itself. Use even when the wording is generic ("save data locally", "remember the user's choice", "let the user pick options in the phone settings") - Zepp OS has three distinct storage mechanisms (phone settingsStorage, watch LocalStorage, watch @zos/fs) with different scopes and types. Do not use for sensor reads (zepp-os-sensors), UI widgets on the watch (zepp-os-ui), navigation (zepp-os-navigation-lifecycle), or watchface rendering (zepp-os-watchface).

Use for creating, drawing, showing, or laying out any on-watch UI in a Zepp OS device app page or watchface - widgets via createWidget(widget.TYPE, ...), widget.TEXT / BUTTON / IMG / ARC / CIRCLE / CANVAS / GRADIENT_POLYGON / SCROLL_LIST / PAGE_SCROLL, showing text / labels / buttons / images, scrollable lists, arcs and progress rings, canvas custom drawing (lines, shapes, paths), handling tap / click / long-press / drag / swipe / move events on widgets, reading or updating widget properties, or px() screen adaptation. Use even when the task sounds like generic UI ("show an image", "make a scrollable list", "handle a tap on a button", "respond to swipe") - Zepp OS uses imperative @zos/ui createWidget, not JSX or HTML.

Use whenever the project is a Zepp OS watchface, watch face, clock face, or dial rather than a regular Mini Program app - configuring appType "watchface" and module.watchface.path in app.json, the WatchFace() entry (one render surface, no pages, no router), drawing the current time / date / seconds, building a digital or analog clock that redraws on tick, adding complications (heart rate, battery, weather), AOD / Always-On Display, edit mode so users can customize widgets, the lockscreen flag, or choosing Watchface Maker (no-code) vs a coded watchface project. Use even when the user says just "clock face", "dial", or "lockscreen" - watchface is a distinct appType, not a regular app. Do not use for normal pages-with-navigation apps (zepp-os-fundamentals + zepp-os-navigation-lifecycle).

Use when the task is about the Zepp OS Zeus command line tool, @zeppos/zeus-cli, or the zeus command - creating projects, previewing in the simulator, live preview, building or packaging .zab output, QR install/deploy to a watch, login, config, developer bridge, or compiling Mini Program/watchface projects.