axiom-apple-docs

어떤 스킬인가요?

Use when ANY question involves Apple framework APIs, Swift compiler errors, or Xcode-bundled documentation. Covers Liquid Glass, Swift 6.2 concurrency, Foundation Models, SwiftData, StoreKit, 32 Swift compiler diagnostics.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

---
name: axiom-apple-docs
description: Use when ANY question involves Apple framework APIs, Swift compiler errors, or Xcode-bundled documentation. Covers Liquid Glass, Swift 6.2 concurrency, Foundation Models, SwiftData, StoreKit, 32 Swift compiler diagnostics.
license: MIT
---

# Apple Documentation Router

Apple bundles for-LLM markdown documentation inside Xcode. These are authoritative, up-to-date guides and diagnostics written by Apple engineers. Read them directly with Claude Code's native **`Read`** tool — no MCP server or special tool required.

## When to Use

- You need the exact API signature or behavior from Apple
- An Axiom skill references an Apple framework and you want the official source
- A Swift compiler diagnostic needs explanation
- The user asks about a specific Apple framework feature

**Priority**: Axiom skills provide opinionated guidance (decision trees, anti-patterns, pressure scenarios). Apple docs provide authoritative API details. Use both together.

## How to Read These Docs

The session-start hook resolves Xcode's location and echoes the literal base directories into session context (look for "Apple for-LLM Documentation: Xcode detected at `<path>`"). Use the **`Read`** tool with `<that base>/<filename>`.

Default Xcode location (`/Applications/Xcode.app`) base directories:

| Content | Base directory |
|---|---|
| AdditionalDocumentation guides | `/Applications/Xcode.app/Contents/PlugIns/IDEIntelligenceChat.framework/Versions/A/Resources/AdditionalDocumentation/` |
| Swift compiler diagnostics | `/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/doc/swift/diagnostics/` |

Example invocation Claude should produce:

```
Read /Applications/Xcode.app/Contents/PlugIns/IDEIntelligenceChat.framework/Versions/A/Resources/AdditionalDocumentation/SwiftUI-Implementing-Liquid-Glass-Design.md
```

Xcode-beta users: the session-start hook respects `AXIOM_XCODE_PATH` and reports the resolved path in session context — use that path, not the default above.

## Guide Files (AdditionalDocumentation)

20 files. Read with the path pattern `{guides base}/{filename}`.

### UI & Design

| Topic | Filename |
|---|---|
| Liquid Glass in SwiftUI | `SwiftUI-Implementing-Liquid-Glass-Design.md` |
| Liquid Glass in UIKit | `UIKit-Implementing-Liquid-Glass-Design.md` |
| Liquid Glass in AppKit | `AppKit-Implementing-Liquid-Glass-Design.md` |
| Liquid Glass in WidgetKit | `WidgetKit-Implementing-Liquid-Glass-Design.md` |
| SwiftUI new toolbar features | `SwiftUI-New-Toolbar-Features.md` |
| SwiftUI styled text editing | `SwiftUI-Styled-Text-Editing.md` |
| SwiftUI WebKit integration | `SwiftUI-WebKit-Integration.md` |
| SwiftUI AlarmKit integration | `SwiftUI-AlarmKit-Integration.md` |
| Swift Charts 3D visualization | `Swift-Charts-3D-Visualization.md` |
| Foundation AttributedString updates | `Foundation-AttributedString-Updates.md` |

### Data & Persistence

| Topic | Filename |
|---|---|
| SwiftData class inheritance | `SwiftData-Class-Inheritance.md` |

### Concurrency & Performance

| Topic | Filename |
|---|---|
| Swift concurrency updates | `Swift-Concurrency-Updates.md` |
| InlineArray and Span | `Swift-InlineArray-Span.md` |

### Apple Intelligence

| Topic | Filename |
|---|---|
| Foundation Models (on-device LLM) | `FoundationModels-Using-on-device-LLM-in-your-app.md` |

### System Integration

| Topic | Filename |
|---|---|
| App Intents updates | `AppIntents-Updates.md` |
| StoreKit updates | `StoreKit-Updates.md` |
| MapKit GeoToolbox PlaceDescriptors | `MapKit-GeoToolbox-PlaceDescriptors.md` |
| Widgets for visionOS | `Widgets-for-visionOS.md` |

### Accessibility

| Topic | Filename |
|---|---|
| Assistive Access in iOS | `Implementing-Assistive-Access-in-iOS.md` |

### Computer Vision

| Topic | Filename |
|---|---|
| Visual Intelligence in iOS | `Implementing-Visual-Intelligence-in-iOS.md` |

## Swift Compiler Diagnostics

46 files in the diagnostics directory. Read with the path pattern `{diagnostics base}/{filename}`.

### Concurrency Diagnostics

| Diagnostic | Filename |
|---|---|
| Actor-isolated call from nonisolated context | `actor-isolated-call.md` |
| Conformance isolation | `conformance-isolation.md` |
| Isolated conformances | `isolated-conformances.md` |
| Nonisolated nonsending by default | `nonisolated-nonsending-by-default.md` |
| Sendable closure captures | `sendable-closure-captures.md` |
| Sendable metatypes | `sendable-metatypes.md` |
| Explicit Sendable annotations | `explicit-sendable-annotations.md` |
| Sending closure risks data race | `sending-closure-risks-data-race.md` |
| Sending risks data race | `sending-risks-data-race.md` |
| Mutable global variable | `mutable-global-variable.md` |
| Preconcurrency import | `preconcurrency-import.md` |
| Dynamic exclusivity | `dynamic-exclusivity.md` |
| Exclusivity violation | `exclusivity-violation.md` |

### Type System Diagnostics

| Diagnostic | Filename |
|---|---|
| Existential any | `existential-any.md` |
| Existential member access limitations | `existential-member-access-limitations.md` |
| Nominal types | `nominal-types.md` |
| Multiple inheritance | `multiple-inheritance.md` |
| Protocol type non-conformance | `protocol-type-non-conformance.md` |
| Opaque type inference | `opaque-type-inference.md` |
| Foreign reference type | `foreign-reference-type.md` |

### Build & Migration Diagnostics

| Diagnostic | Filename |
|---|---|
| Deprecated declaration | `deprecated-declaration.md` |
| Error in future Swift version | `error-in-future-swift-version.md` |
| Strict language features | `strict-language-features.md` |
| Strict memory safety | `strict-memory-safety.md` |
| Implementation only deprecated | `implementation-only-deprecated.md` |
| Member import visibility | `member-import-visibility.md` |
| Missing module on known paths | `missing-module-on-known-paths.md` |
| Module not testable | `module-not-testable.md` |
| Module version missing | `module-version-missing.md` |
| Clang declaration import | `clang-declaration-import.md` |
| Availability unrecognized name | `availability-unrecognized-name.md` |
| Always-available domain | `always-available-domain.md` |
| Upcoming language features | `upcoming-language-features.md` |
| Unknown warning group | `unknown-warning-group.md` |
| Compilation caching | `compilation-caching.md` |
| Embedded restrictions | `embedded-restrictions.md` |

### Swift Language Diagnostics

| Diagnostic | Filename |
|---|---|
| Dynamic callable requirements | `dynamic-callable-requirements.md` |
| Property wrapper requirements | `property-wrapper-requirements.md` |
| Result builder methods | `result-builder-methods.md` |
| String interpolation conformance | `string-interpolation-conformance.md` |
| Trailing closure matching | `trailing-closure-matching.md` |
| Temporary pointers | `temporary-pointers.md` |
| Semantic copies | `semantic-copies.md` |
| Performance hints | `performance-hints.md` |

### Index

| Diagnostic | Filename |
|---|---|
| Diagnostic groups (taxonomy) | `diagnostic-groups.md` |
| All diagnostics index | `diagnostics.md` |

If a diagnostic you need isn't listed above, list the diagnostics directory first:

```
ls $AXIOM_XCODE_PATH/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/doc/swift/diagnostics/
```

Filenames follow the diagnostic's short name (lowercase, hyphenated).

## Routing Decision Tree

```
User question about Apple API/framework?
├── Specific compiler error/warning → Read {diagnostics base}/<diagnostic-name>.md
├── Liquid Glass implementation     → Read {guides base}/<Framework>-Implementing-Liquid-Glass-Design.md
├── Swift concurrency patterns      → Read {guides base}/Swift-Concurrency-Updates.md
├── Foundation Models / on-device AI → Read {guides base}/FoundationModels-Using-on-device-LLM-in-your-app.md
├── SwiftData features              → Read {guides base}/SwiftData-Class-Inheritance.md
├── StoreKit / IAP                  → Read {guides base}/StoreKit-Updates.md
├── App Intents / Siri              → Read {guides base}/AppIntents-Updates.md
├── Charts / visualization          → Read {guides base}/Swift-Charts-3D-Visualization.md
├── Text editing / AttributedString → Read {guides base}/SwiftUI-Styled-Text-Editing.md or Foundation-AttributedString-Updates.md
├── WebKit in SwiftUI               → Read {guides base}/SwiftUI-WebKit-Integration.md
├── Toolbar features                → Read {guides base}/SwiftUI-New-Toolbar-Features.md
└── Other                           → ls the base directory to see what's available
```

## Fallback When Xcode Is Unavailable

If `AXIOM_XCODE_PATH` is unset, or the path doesn't exist, or the `IDEIntelligenceChat.framework` directory is missing (older Xcode), fall back to:

1. **sosumi.ai** (markdown mirror of developer.apple.com — see `skills/apple-docs-research.md`)
2. **WebFetch** of the equivalent developer.apple.com URL
3. **Suggest** installing the latest Xcode for full Apple docs coverage

Do not silently fail — tell the user when Xcode docs aren't available locally and which fallback you used.

## MCP Convenience Path

Clients using axiom-mcp can also invoke `axiom_read_skill` with the legacy ID (e.g., `apple-guide-swiftui-implementing-liquid-glass-design`). The MCP server reads the same Xcode files and returns the same content. Both paths are supported — the file-Read path works everywhere; the MCP path is a convenience for catalog/search workflows.

## Research Methodology

For WWDC transcript capture (Chrome auto-capture), sosumi.ai documentation access, and multi-session research workflows, see [skills/apple-docs-research.md](skills/apple-docs-research.md).

## Resources

**Skills**: axiom-swiftui, axiom-concurrency, axiom-data, axiom-ai, axiom-integration

# Apple Documentation Research

## When to Use This Skill

✅ **Use this skill when**:
- Researching Apple frameworks or APIs (WidgetKit, SwiftUI, etc.)
- Need full WWDC session transcripts with code samples
- Looking for Apple Developer documentation
- Want to extract code examples from WWDC presentations
- Building comprehensive skills based on Apple technologies

❌ **Do NOT use this skill for**:
- Third-party framework documentation
- General web research
- Questions already answered in existing skills
- Basic Swift language questions (use Swift documentation)

## Related Skills

- Use **superpowers-chrome:browsing** for interactive browser control
- Use **writing-skills** when creating new skills from Apple documentation
- Use **reviewing-reference-skills** to validate Apple documentation skills

## Core Philosophy

> Apple Developer video pages contain full verbatim transcripts with timestamps and complete code samples. Chrome's auto-capture feature makes this content instantly accessible without manual copying.

**Key insight**: Don't manually transcribe or copy code from WWDC videos. The transcripts are already on the page, fully timestamped and formatted.

## WWDC Session Transcripts via Chrome

### The Technique

Apple Developer video pages (`developer.apple.com/videos/play/wwdc20XX/XXXXX/`) contain complete transcripts that Chrome auto-captures.

#### Step-by-Step Process

1. **Navigate** using Chrome browser MCP tool:
   ```json
   {
     "action": "navigate",
     "payload": "https://developer.apple.com/videos/play/wwdc2025/278/"
   }
   ```

   Tool name: `mcp__plugin_superpowers-chrome_chrome__use_browser`

   **Complete invocation**:
   ```
   Use the mcp__plugin_superpowers-chrome_chrome__use_browser tool with:
   - action: "navigate"
   - payload: "https://developer.apple.com/videos/play/wwdc2025/278/"
   ```

2. **Locate** the auto-captured file:
   - Chrome saves to: `~/.../superpowers/browser/YYYY-MM-DD/session-TIMESTAMP/`
   - Session directory uses Unix timestamp in milliseconds (e.g., `session-1765217804099`)
   - Filename pattern: `NNN-navigate.md` (e.g., `001-navigate.md`)

   **Finding the latest session**:
   ```bash
   # List sessions sorted by modification time (newest first)
   ls -lt ~/Library/Caches/superpowers/browser/*/session-* | head -5
   ```

3. **Read** the captured transcript:
   - Full spoken content with timestamps (e.g., `[0:07]`, `[1:23]`)
   - Descriptions of code and API usage (spoken, not formatted)
   - Chapter markers and resource links

### What You Get

**✅ WWDC transcripts contain:**
- Full spoken content with timestamps (e.g., `[0:07]`, `[1:23]`)
- API names mentioned by speakers (e.g., `widgetRenderingMode`, `supportedMountingStyles`)
- Descriptions of what code does ("I'll add the widgetRenderingMode environment variable")
- Step-by-step explanations of implementations
- Chapter markers and resource links

**❌ WWDC transcripts do NOT contain:**
- Formatted Swift code blocks ready to copy-paste
- Complete implementations
- Structured code examples

**Critical Understanding**: Transcripts are **spoken word, not code**. You'll read sentences like "I'll add the widgetRenderingMode environment variable to my widget view" and need to **reconstruct the code yourself** from these descriptions.

### When Code Isn't Clear from Transcript

If the transcript's code descriptions aren't detailed enough, follow this fallback workflow:

1. **Check Resources Tab**
   - Navigate back to the WWDC session page
   - Click "Resources" tab
   - Look for "Download Sample Code" or "View on GitHub"
   - Download Xcode project with complete working implementation

2. **Use sosumi.ai for API Details**
   - Look up specific APIs mentioned in transcript
   - Example: Transcript says "widgetAccentedRenderingMode" → look up `sosumi.ai/documentation/swiftui/widgetaccentedrenderingmode`
   - Get exact signature, parameters, usage

3. **Jump to Timestamp in Video**
   - Use transcript timestamp to jump directly to code explanation in video
   - Example: Transcript says code at `[4:23]` → watch that specific 30-second segment
   - Faster than watching entire 45-minute session

4. **Combine Sources**
   - Transcript = conceptual understanding + workflow
   - Resources = complete code
   - sosumi.ai = API details
   - Result: Full picture without manually reconstructing everything

**Example transcript structure**:
```markdown
# Session Title - WWDC## - Videos - Apple Developer

## Chapters
- 0:00 - Introduction
- 1:23 - Key Topic 1

## Transcript
0:00
Speaker: Welcome to this session...

[timestamp]
Now I'll add the widgetAccentedRenderingMode modifier...
```

### Example Session

**WWDC 2025-278** "What's new in widgets":
- Navigate: `https://developer.apple.com/videos/play/wwdc2025/278/`
- Captured: `001-navigate.md`
- Contains: ~15 minutes of full transcript with API references and code concepts

## Apple Documentation via sosumi.ai

### Why sosumi.ai

Developer.apple.com documentation is HTML-heavy and difficult to parse. sosumi.ai provides the same content in clean markdown format.

### URL Pattern

**Instead of**:
```
https://developer.apple.com/documentation/widgetkit
```

**Use**:
```
https://sosumi.ai/documentation/widgetkit
```

### URL Pattern Rules

**Format**: `https://sosumi.ai/documentation/[framework]`

**Rules for framework name**:
1. **Lowercase** - Use lowercase even if framework is capitalized (SwiftUI → swiftui)
2. **No spaces** - Remove all spaces (Core Data → coredata)
3. **No hyphens** - Remove all hyphens (App Intents → appintents, NOT app-intents)
4. **Case-insensitive** - Both `SwiftUI` and `swiftui` work, but lowercase is recommended

**Common mistakes**:
- ❌ `app-intents` → ✅ `appintents`
- ❌ `axiom-data (skills/core-data.md)` → ✅ `coredata`
- ❌ `AVFoundation` → ✅ `avfoundation`

**Examples**:
| Framework Name | sosumi.ai URL |
|----------------|---------------|
| SwiftUI | `sosumi.ai/documentation/swiftui` |
| App Intents | `sosumi.ai/documentation/appintents` |
| Core Data | `sosumi.ai/documentation/coredata` |
| AVFoundation | `sosumi.ai/documentation/avfoundation` |
| UIKit | `sosumi.ai/documentation/uikit` |

### Using with WebFetch or Read Tools

```
WebFetch:
  url: https://sosumi.ai/documentation/widgetkit/widget
  prompt: "Extract information about Widget protocol"

Result: Clean markdown with API signatures, descriptions, examples
```

### Framework Examples

| Framework | sosumi.ai URL |
|-----------|---------------|
| WidgetKit | `https://sosumi.ai/documentation/widgetkit` |
| SwiftUI | `https://sosumi.ai/documentation/swiftui` |
| ActivityKit | `https://sosumi.ai/documentation/activitykit` |
| App Intents | `https://sosumi.ai/documentation/appintents` |
| Foundation | `https://sosumi.ai/documentation/foundation` |

## Common Research Workflows

### Workflow 1: New iOS Feature Research

**Goal**: Create a comprehensive skill for a new iOS 26 feature.

1. **Find WWDC sessions** — Search "WWDC 2025 [feature name]"
2. **Get transcripts** — Navigate with Chrome to each session
3. **Read transcripts** — Extract key concepts, code patterns, gotchas
4. **Get API docs** — Use sosumi.ai for framework reference
5. **Cross-reference** — Verify code samples match documentation
6. **Create skill** — Combine transcript insights + API reference

**Time saved**: 3-4 hours vs. watching videos and manual transcription

### Workflow 2: API Deep Dive

**Goal**: Understand a specific API or protocol.

1. **sosumi.ai docs** — Get protocol/class definition
2. **WWDC sessions** — Search for sessions mentioning the API
3. **Code samples** — Extract from transcript code blocks
4. **Verify patterns** — Ensure examples match latest API

### Workflow 3: Multiple Sessions Research

**Goal**: Comprehensive coverage across multiple years (e.g., widgets evolution).

1. **Parallel navigation** — Use Chrome to visit 3-6 sessions
2. **Read all transcripts** — Compare how APIs evolved
3. **Extract timeline** — iOS 14 → 17 → 18 → 26 changes
4. **Consolidate** — Create unified skill with version annotations

**Example**: Extensions & Widgets skill used 6 WWDC sessions (2023-2025)

## Anti-Patterns

### ❌ DON'T: Manual Video Watching

```
BAD:
1. Play WWDC video
2. Pause and take notes
3. Rewind to capture code
4. Type out examples manually

Result: 45 minutes per session
```

### ✅ DO: Chrome Auto-Capture

```
GOOD:
1. Navigate with Chrome
2. Read captured .md file
3. Copy code blocks directly
4. Reference timestamps for context

Result: 5 minutes per session
```

### ❌ DON'T: Scrape developer.apple.com HTML

```
BAD:
Use WebFetch on developer.apple.com/documentation
Result: Complex HTML parsing required
```

### ✅ DO: Use sosumi.ai

```
GOOD:
Use WebFetch on sosumi.ai/documentation
Result: Clean markdown, instant access
```

## Troubleshooting

### superpowers-chrome MCP not available

**Symptom**: `mcp__plugin_superpowers-chrome_chrome__use_browser` isn't loaded in this session.

**Solution**: Fall back to the `agent-browser` CLI (`/opt/homebrew/bin/agent-browser`) to fetch the page, then read its output. Don't give up on the content or kill the user's Chrome — launch a separate profile instead if a live browser is required.

### Chrome Session Directory Not Found

**Symptom**: Can't locate `001-navigate.md` file

**Solution**:
1. Check Chrome actually navigated (look for URL confirmation)
2. Find latest session: `ls -lt ~/Library/Caches/superpowers/browser/*/`
3. Session directory format: `YYYY-MM-DD/session-TIMESTAMP/`

### Transcript Incomplete

**Symptom**: File exists but missing transcript

**Solution**:
1. Page may still be loading - wait 2-3 seconds
2. Try navigating again
3. Some sessions require scrolling to load full content

### sosumi.ai Returns Error

**Symptom**: 404 or invalid URL

**Solution**:
1. Verify framework name spelling
2. Check sosumi.ai format: `/documentation/[frameworkname]`
3. Fallback: Use developer.apple.com but expect HTML

## Verification Checklist

Before using captured content:
- ☐ Transcript includes timestamps
- ☐ Code samples are complete (not truncated)
- ☐ Speaker names and chapter markers present
- ☐ Multiple speakers properly attributed
- ☐ Code syntax highlighting preserved

## Resources

**Skills**: superpowers-chrome:browsing, writing-skills, reviewing-reference-skills

**Time Saved**: Using this technique saves 30-40 minutes per WWDC session vs. manual video watching and transcription. For comprehensive research spanning multiple sessions, savings compound to 3-4 hours per skill.