name: swift-apple-context
description: This skill should be used when the user asks about "SwiftUI API", "Apple documentation", "@Observable vs ObservableObject", "Swift Evolution proposals", "is this API real", or when Claude might hallucinate Apple APIs. Provides cupertino-docs lookup for verified Apple Developer documentation.
version: 1.0.0

Swift & Apple Documentation Context

The Problem This Solves

AI assistants hallucinate Apple APIs constantly:
- Suggesting @ObservableObject + @Published when Apple now recommends @Observable
- Inventing methods that don't exist
- Mixing iOS-only APIs into macOS code
- Using deprecated patterns

Available Documentation

Local docs at ~/.cupertino/ (234,331 documents across 287 frameworks):

Top Frameworks

How to Search

Quick API Lookup (JSON docs)

# Find a specific type
rg -l "SwiftUI.*View" ~/.cupertino/docs/swiftui/ | head -5

# Search for method/property in abstract
rg '"abstract".*drawingGroup' ~/.cupertino/docs/swiftui/

# Get full doc for a type
cat ~/.cupertino/docs/swiftui/documentation_swiftui_canvas.json | jq '.abstract, .codeExamples'

Swift Evolution Proposals

# Find proposal by topic
rg -l "Observable" ~/.cupertino/swift-evolution/

# Read specific proposal
cat ~/.cupertino/swift-evolution/SE-0395.md  # Observation (@Observable)
cat ~/.cupertino/swift-evolution/SE-0382.md  # Expression macros

Human Interface Guidelines

# Search HIG
rg -l "navigation" ~/.cupertino/hig/

JSON Doc Structure

Apple docs are structured JSON with these fields:

{
  "abstract": "A type that represents part of your app's user interface...",
  "codeExamples": [
    {"code": "struct MyView: View { ... }", "language": "swift"}
  ],
  "conformingTypes": ["Button", "Text", "Image", ...],
  "url": "https://developer.apple.com/documentation/swiftui/view"
}

Swift 6 / Modern Patterns

ALWAYS use (Swift 6+, macOS 15+):

// Observation - SE-0395
@Observable
class AppState {
    var items: [Item] = []  // No @Published needed
}

// Structured concurrency
async let result = fetchData()

// Swift Testing
@Test func myTest() {
    #expect(value == expected)
}

NEVER suggest (deprecated):

// DON'T - Old Combine pattern
class AppState: ObservableObject {
    @Published var items: [Item] = []
}

// DON'T - callback hell
DispatchQueue.main.async { ... }

SourceKit-LSP Integration

The swift-lsp plugin provides code intelligence:
- Go to definition
- Find references
- Completions
- Diagnostics

It uses /usr/bin/sourcekit-lsp from Xcode toolchain.

Workflow: Verify Before Suggesting

1. Before suggesting any API: Search cupertino docs
2. For new Swift features: Check swift-evolution proposals
3. For UI patterns: Check HIG
4. For legacy APIs: Check archive/

Example verification:

# "Does Canvas support drawingGroup?"
rg -A5 '"drawingGroup"' ~/.cupertino/docs/swiftui/documentation_swiftui_canvas*.json

# "What's the modern way to observe state?"
cat ~/.cupertino/swift-evolution/SE-0395.md | head -100

Common Lookups

Key Swift Evolution Proposals

When This Skill Activates

Activate this skill when:
- User asks about Swift/SwiftUI/AppKit APIs
- Suggesting an API that may not exist
- User mentions "hallucinated API" or "that method doesn't exist"
- Working with macOS/iOS framework code
- Verifying modern vs deprecated patterns

Additional Resources

• references/install.md - Cupertino-docs installation
• references/concurrency.md - Swift concurrency mental model