I recently had to refactor a React Native app to native SwiftUI because of CarPlay.
There was no real alternative. If I wanted proper CarPlay support, SwiftUI was the path forward.
I had very little recent experience with SwiftUI, but I wasn't too worried. I assumed AI agents would carry most of the rewrite. I'd used Claude Code, Codex, and similar tools successfully for large refactors before.
This time, it didn't work.
The problem wasn't syntax
The SwiftUI code the agents produced was technically correct. It compiled. It even looked reasonable at a glance.
But structurally, it was wrong.
State lived in the wrong places. Views were composed poorly. Navigation felt off. Previews were either missing or not useful. The code didn't feel like something Apple would ship.
Fixing one issue usually created two more.
That's when I noticed something interesting.
Xcode's AI behaved differently
When I tried the built-in AI companion inside Xcode, the output was noticeably better.
Not perfect. But better.
The structure made more sense. The patterns were more idiomatic. There were fewer strange abstractions and fewer "almost SwiftUI" solutions.
This raised a question:
Why would Xcode's AI behave better than general-purpose agents, even when those agents are using stronger models?
The answer turned out to be simple.
Apple already wrote the missing context
Inside Xcode, there is a directory most developers never look at:
/Applications/Xcode.app/Contents/PlugIns/
IDEIntelligenceChat.framework/Versions/A/Resources/AdditionalDocumentation
That folder contains a set of Apple-authored documents.
These are not marketing docs or beginner tutorials. They are internal guidance documents that encode how Apple expects developers to use SwiftUI and related frameworks.
They are designed to make Apple's own tools behave correctly, not to teach the public.
They cover topics like:
- SwiftUI composition patterns
- App Intents and system integrations
- StoreKit flows
- AlarmKit
- WebKit integration in SwiftUI
- SwiftData inheritance
- Swift Concurrency updates
- Liquid Glass design across SwiftUI, UIKit, AppKit, and WidgetKit
- Widgets for visionOS
- Low-level Swift performance primitives
In other words, exactly the areas where AI agents struggle most.
This explains why AI struggles with SwiftUI
SwiftUI isn't difficult because the syntax is complex.
It's difficult because it's opinionated.
Many of its architectural constraints are implicit. Apple assumes you understand them. Public documentation often shows what to do, but not how Apple expects you to think when doing it.
General-purpose AI agents do not have that mental model.
Xcode's AI does, because it has access to Apple's internal guidance.
Turning Apple's guidance into a skill
Once I found these documents, the path forward was obvious.
Instead of hoping models would infer SwiftUI patterns, I could explicitly give agents the same guidance Apple uses internally.
I packaged that documentation into a set of skills that AI agents can reference when generating or refactoring SwiftUI code.
The impact was immediate:
- Fewer hallucinated APIs
- Better state placement
- More idiomatic view composition
- Code that felt closer to real Apple examples
The models did not change.
The context did.
Introducing swiftui-skills
I turned this into an open-source project called swiftui-skills.
It:
- Extracts Apple-authored documentation from your local Xcode install
- Packages it as reusable skills for AI coding agents
- Works with tools like Claude Code, Cursor, Codex, and others
- Is local-first and open source
- Does not redistribute Apple documentation
The goal is simple:
Give AI agents the same SwiftUI context that Apple provides to Xcode.
The bigger takeaway
This changed how I think about AI-assisted coding.
Model quality matters, but context matters more.
Framework authors already encode their expectations. Often, that guidance exists inside tooling rather than public documentation.
If we want AI to write better code, we need to give it the same constraints and context that framework authors give their own tools.
SwiftUI just makes that gap obvious.
The project lives at: swiftui-skills.ameyalambat.com
X article: x.com/lambatameya/status/2012615018873811334
The code is open source.