create-watchos-version
分析现有的 iOS/macOS/Apple 平台项目,为构建 watchOS 配套或独立应用程序创建全面的分阶段计划。当用户想要向现有 Apple 平台应用程序添加 watchOS 支持、创建其 iOS 应用程序的 Watch 应用程序版本或构建 watchOS 功能时使用。该技能会消化项目架构、识别模式、分析 API 兼容性、搜索当前的 watchOS 文档,并在生成任何代码之前生成详细的实施计划以及 API 可用性警告。
name: create-watchos-version description: Analyzes existing iOS/macOS/Apple platform projects to create a comprehensive, phased plan for building a watchOS companion or standalone app. Use when users want to add watchOS support to an existing Apple platform app, create a Watch app version of their iOS app, or build watchOS features. The skill digests project architecture, identifies patterns, analyzes API compatibility, searches for current watchOS documentation, and produces a detailed implementation plan with API availability warnings before any code generation.
Create watchOS Version
Analyzes existing Apple platform projects and creates detailed, phased implementation plans for watchOS apps that are elegant, top-tier experiences—not naive skins of the parent app.
Workflow
- Project Discovery - Analyze project structure, patterns, architecture
- Feature Mapping - Identify watchOS-suitable features and priorities
- API Compatibility - Search web for current watchOS API availability
- Architecture Planning - Design watchOS-specific architecture
- Plan Generation - Create phased plan with warnings and alternatives
- User Review - Present plan for approval before implementation
Phase 1: Project Discovery
Scan project root for:
├── App Architecture (SwiftUI, UIKit, AppKit, hybrid)
├── Data Layer (Core Data, SwiftData, Realm, custom)
├── Networking (URLSession, Alamofire, custom)
├── State Management (ObservableObject, TCA, Redux-like)
├── Navigation (NavigationStack, Coordinator)
├── Shared Frameworks (SPM packages, shared targets)
├── Assets (colors, images, SF Symbols)
├── Existing Watch Target (if any)
└── Minimum iOS Version (affects watchOS targeting)
Key files: *.xcodeproj, Package.swift, Info.plist, App entry points, ViewModels, Models.
Phase 2: Feature Mapping
Glanceable (High Priority): Status displays, counters, progress, recent items, quick stats
Quick Actions (High Priority): Single-tap toggles, shortcuts, haptic confirmations
Complications/Widgets (Critical): Map data to WidgetKit families—accessoryCircular, accessoryRectangular, accessoryInline, accessoryCorner. Consider Smart Stack relevance.
Background: HealthKit integration, background refresh, Watch Connectivity sync
Defer/Exclude: Complex data entry, long-form content, sustained screen time features
Phase 3: API Compatibility
CRITICAL: Always search web for current watchOS docs before finalizing. APIs change frequently.
Search: [FrameworkName] watchOS availability site:developer.apple.com
Quick Reference
Available: SwiftUI, SwiftData (10+), WidgetKit (9+), HealthKit, WorkoutKit, CoreLocation (limited), WatchConnectivity, CloudKit, CoreMotion, AVFoundation (audio), CoreBluetooth, Combine, Swift Concurrency
Unavailable/Limited: UIKit, WebKit, MapKit (limited), CoreImage (limited), ARKit, RealityKit, StoreKit (limited), Background URLSession (limited)
See references/api-compatibility.md for detailed compatibility matrix.
Phase 4: Architecture
Version Targeting
iOS 16+ → watchOS 9+ (WidgetKit complications)
iOS 17+ → watchOS 10+ (SwiftData, Smart Stack)
iOS 18+ → watchOS 11+ (Live Activities on Watch)
Structure
Shared/
├── Models/ # Pure Swift, shared via target membership
├── Services/ # Platform-agnostic logic
└── Utilities/
WatchApp/
├── App.swift
├── Views/
├── ViewModels/
├── Complications/
└── WatchConnectivity/
Design Principles
- Glanceability - Visible within 2 seconds
- Minimal Interaction - 1-3 taps max
- Context Awareness - Time, location, activity
- Battery Conscious - Efficient refresh, TimelineSchedule
- Haptic Feedback - Confirm actions appropriately
SwiftUI Gotchas
- Avoid nested TabViews (memory leaks)
- Use TimelineSchedule for efficient metric updates
- Check
isLuminanceReducedto reduce work when dimmed - Don't use data-driven high-frequency UI refreshes
Phase 5: Plan Generation
Use template in references/plan-template.md to generate:
- Executive Summary
- ⚠️ API Compatibility Warnings table
- Phased implementation tasks
- Testing checklist
Phase 6: User Review
Present plan and ask for approval before implementing:
"I've analyzed your project and created a watchOS plan. Before proceeding:
- API Warnings: [N] APIs unavailable—alternatives documented.
- Recommended Features: [list] prioritized for Watch.
- Scope: [N] phases.
Proceed with implementation, or adjust the plan?"
Do not implement until user approves.
Best Practices Reference
Watch Connectivity
guard WCSession.default.activationState == .activated else { return }
// sendMessage: immediate, requires reachability
// transferUserInfo: queued, guaranteed
// transferCurrentComplicationUserInfo: complication priority
Complications
// Use appropriate reload policy
Timeline(entries: entries, policy: .after(nextUpdateDate))
// Use .never for static complications
Battery Efficiency
- Timeline-based over active refresh
- Check
isLuminanceReduced - Batch Watch Connectivity transfers
- Significant location change vs continuous updates