watchOS Development

You MUST use this skill for ANY watchOS-specific development including app structure, independent apps, Watch Connectivity, complications and Smart Stack widgets, controls, Live Activities on watch, background tasks, and ClockKit migration.

Auditors are skills here. Where this router says "Launch some-auditor agent", invoke the matching Codex skill instead — same procedure, no Claude Code agent required.

Available: axiom-modernize.

The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run.

Quick Reference

Cross-Suite Routes

These topics overlap with watchOS development but live in separate suites:

SwiftUI (shared iOS/watchOS/macOS)

• View state, data flow, @Observable → See axiom-swiftui
• Navigation basics (NavigationStack) → See axiom-swiftui
• Layout, animations → See axiom-swiftui

Design

• General HIG, Liquid Glass, SF Symbols, typography → See axiom-design

Accessibility

• General VoiceOver, Dynamic Type, WCAG → See axiom-accessibility
• watchOS-specific (VoiceOver rotor on Digital Crown, AssistiveTouch, Double Tap) → See axiom-accessibility (skills/watchos-a11y.md)

Health and workouts

• HealthKit, HKWorkoutSession, HKLiveWorkoutBuilder, WorkoutKit → See axiom-health
• Workout recovery, multi-device coordination → See axiom-health (skills/workouts.md)

iOS-side widgets and App Intents

• iOS/iPadOS widgets, configuration intents, App Intents → See axiom-integration
• Live Activities on iPhone (initiation + ActivityKit) → See axiom-integration

Concurrency

• Swift 6 concurrency, actors, Sendable → See axiom-concurrency

New-on-watch frameworks (27 releases)

• Foundation Models depth (sessions, @Generable, tools, PCC) → See axiom-ai; watch scoping is in skills/platform-basics.md
• Vision framework (new on watchOS 27) → See axiom-vision
• NowPlaying / MusicUnderstanding (new on watchOS 27) → See axiom-media

Conflict Resolution

axiom-watchos vs axiom-swiftui: When building a watchOS SwiftUI app:

1. Use axiom-watchos for watch-specific patterns: glanceable UI, constrained navigation, Digital Crown focus, Smart Stack placement
2. Use axiom-swiftui for cross-platform SwiftUI: state management, layout primitives, animations
3. Both may apply: A watchOS NavigationStack with complications needs axiom-watchos for complication surfaces and axiom-swiftui for NavigationStack basics

axiom-watchos vs axiom-integration: For widgets and Live Activities:

1. Use axiom-watchos for watch complications, Smart Stack placement, watch-side Live Activity presentation, RelevanceKit
2. Use axiom-integration for iOS/iPadOS widgets, core ActivityKit API, App Intents

watch-device-diag vs watch-connectivity: Two independent connections fail in ways that look identical. Decide which before writing any code:

1. Use watch-device-diag for the Mac/Xcode → Watch link (CoreDevice): install, launch, LLDB attach, a Watch that is missing or unavailable
2. Use watch-connectivity for the iPhone app ↔ watchOS app link (WCSession): transfer-API choice, delivery semantics, background-task completion
3. When unsure, start with watch-device-diag. Run the app without the debugger attached — if it behaves correctly, the fault is the tunnel and no WCSession change will help. Redesigning WCSession to compensate for a broken debugger tunnel is the most expensive mistake in watchOS work
4. isReachable == false is not a transport failure — it is the expected value across ordinary lifecycle transitions and routes to watch-connectivity, not here

axiom-watchos vs axiom-health: For workouts on Apple Watch:

1. Use axiom-watchos for watch-specific presentation: Always On display, Smart Stack placement, background mode coordination
2. Use axiom-health for HKWorkoutSession lifecycle, HKLiveWorkoutBuilder, recovery, multi-device mirroring

Decision Tree

digraph watchos {
    start [label="watchOS development task" shape=ellipse];
    what [label="What area?" shape=diamond];

    start -> what;
    what -> "skills/platform-basics.md" [label="app structure, independent apps, submission"];
    what -> "skills/design-for-watchos.md" [label="watch HIG, glanceable UX"];
    what -> "skills/smart-stack-and-complications.md" [label="complications, Smart Stack, RelevanceKit"];
    what -> "skills/controls-and-live-activities.md" [label="controls, watch Live Activities"];
    what -> "skills/watch-connectivity.md" [label="WCSession, paired-device transfer"];
    what -> "skills/watch-device-diag.md" [label="Xcode can't reach the Watch"];
    what -> "skills/background-and-networking.md" [label="background tasks, BGTaskScheduler, networking limits"];
    what -> "skills/platform-basics.md" [label="Foundation Models / PCC on watch"];
    what -> "skills/modernization.md" [label="WatchKit/ClockKit migration"];
    what -> "axiom-health" [label="workouts, HealthKit, WorkoutKit"];
    what -> "axiom-swiftui" [label="general SwiftUI patterns"];
    what -> "axiom-accessibility" [label="VoiceOver rotor, AssistiveTouch"];
    what -> "axiom-integration" [label="iOS-side widgets, App Intents"];
}

Resources

WWDC: 2021-10003, 2022-10133, 2023-10138, 2023-10029, 2023-10309, 2024-10098, 2024-10157, 2024-10205, 2025-334

Docs: /watchos-apps/building_a_watchos_app, /watchos-apps/creating-independent-watchos-apps, /watchconnectivity, /widgetkit/creating-accessory-widgets-and-watch-complications, /widgetkit/converting-a-clockkit-app, /relevancekit, /technotes/tn3135-low-level-networking-on-watchos, /technotes/tn3157-updating-your-watchos-project-for-swiftui-and-widgetkit

Skills: axiom-swiftui, axiom-design, axiom-accessibility, axiom-health, axiom-integration, axiom-concurrency, axiom-ai, axiom-vision, axiom-media