Anmelden
KI-Skills für Swift
Vor zwei Jahren half »Prompt Engineering« zu besseren Ergebnissen bei KI-Tools. Heute ist der Weg ein anderer:
- Die Datei
AGENTS.md(für die meisten KI-Tools) bzw.CLAUDE.md(für Claude Code) im Projektverzeichnis fasst wichtige Projektinformationen und Coding-Anweisungen zusammen. IDEs wie Cursor bzw. CLIs wie Claude Code oder Codex berücksichtigen diese Datei bei jedem Session-Start automatisch. Damit bietet diese Datei eine großartige Möglichkeit, das Default-Verhalten von KI-Tools den eigenen Ansprüchen anzupassen. (AGENTS.mdkönnenCLAUDE.mdauf verschiedenen Ebenen gespeichert werden, um z.B. allgemeine Coding-Anweisungen mit spezifischen Projektinformationen zu kombinieren.) -
Skills ermöglichen es, Anweisungen für bestimmte Bearbeitungsschritte im Markdown-Format zu formulieren. Während
AGENTS.mdimmer berücksichtigt wird, werden Skills nur bei Bedarf ausgewertet. Skills können auch Anweisungen für den Aufruf externer Tools beinhalten und ersetzen dann in manchen Fällen die MCP-Server-Konfiguration. (Auch Skills können wahlweise projektspezifisch oder auf globaler Ebene eingerichtet werden.)
Dieser Beitrag zeigt die Anwendung von AGENTS.md und Skills speziell für die Programmiersprache Swift — losgelöst davon, ob Sie in Xcode arbeiten oder eine externe CLI verwenden. Der Artikel hat einen leichten Claude-Fokus, weil ich mich persönlich in der Anthropic-Welt wohler fühle als in der von OpenAI. Qualitativ gibt es keine großen Unterschiede zwischen beiden Systemen, beide funktionieren mittlerweile herausragend gut.
Ich setze hier voraus, dass Sie grundlegende Erfahrung mit KI-Tools haben und zumindest ein CLI-Tool (ich empfehle Claude Code, aber auch Codex CLI, Gemini CLI, Copilot CLI usw.) ausprobiert haben.
AGENTS.md bzw. CLAUDE.md auf Projekt-Ebene
Wenn Sie in Xcode mit Claude Agent oder Codex arbeiten, sollte Ihr erster Prompt in einem neuen Projekt /init lauten. Der Claude Agent bzw. Codex analysiert dann Ihren Code und erzeugt die Datei CLAUDE.md bzw. AGENTS.md. (AGENTS.md ist ein generischer Name. Die Datei wird von den meisten KI-Tools berücksichtigt, absurderweise aber nicht von Anthropic-Tools, die auf CLAUDE.md bestehen.)
Die Datei wird im Projektverzeichnis gespeichert; sie ist im Projektnavigator unsichtbar, weil dieser eine Verzeichnisebene tiefer ansetzt. Im Regelfall lohnt es sich, diese Datei in einem Editor nachzubearbeiten und dort bei Bedarf eigene Coding-Anweisungen hinzuzufügen.
Beachten Sie, dass die Datei bei jeder Session in den Kontext gelesen wird. Halten Sie sich daher kurz!
Die von Claude Code ohne meine Mithilfe generierte Datei CLAUDE.md für das Cart-Beispielprogramm (Kapitel 25 in meinem Swift-Buch) sieht beispielsweise so aus:
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Build & Run
This is an Xcode project (`family-cart.xcodeproj`). Build and run through Xcode or use the `BuildProject` MCP tool. There are no tests, no linter, and no package dependencies.
## Architecture
**Family Cart** is a SwiftUI shopping list app that syncs across family members via a REST API. The codebase follows a strict three-layer structure reflected in the folder naming:
### 1_model
- **ShoppingItem** — Immutable `struct` (Codable, Identifiable). All mutations produce new copies via the `with(...)` helper. Persisted locally as JSON in the Documents directory (`shoppingItems.json`). The `[ShoppingItem].save()` extension handles local persistence.
- **Category** — `@Observable class` with 10 predefined grocery categories. Each has a `shortcut` string (e.g. `"bread"`, `"veg"`, `"dairy"`) used as the foreign key in ShoppingItem. Categories are not persisted — they are recreated from `predefinedCategories()` on every launch. `Color(hex:)` extension lives here.
...
## Key Patterns
- **No Combine**: The app uses `@Observable` (Observation framework) and Swift concurrency (async/await). Avoid introducing Combine.
- **Immutable model pattern**: `ShoppingItem` is a struct. Always use `with(...)` to create modified copies, then `replaceItem(_:with:)` on the view model. Never mutate items in place.
- **Single ViewModel**: All state flows through `ShoppingViewModel`. Views receive it as a parameter (not via `@Environment`).
- **Categories as constants**: The 10 categories and their shortcuts are hardcoded. Category images use custom assets with `-fill` suffix variants for selected state.
- **Localization**: Strings are localized via `Localizable.xcstrings` (English + German). Category names use `LocalizedStringKey`.
- **Soft delete**: Items are never removed from the array — `deleteItem()` sets `isDeleted = true` and title to `"deleted"`.
## REST API
Backend at `cart.kofler.info:443`. Authentication via HMAC-SHA256 tokens that rotate every 5 minutes. Key endpoints:
- `GET /version` — connectivity test
- `GET/PUT /items/{family_id}` — pull/push shopping items
- `PUT /newfamily`, `PUT /newmember` — family setup
- `GET /family/{code}`, `GET /members/{family_id}` — family lookup
AGENTS.md bzw. CLAUDE.md auf Xcode-Ebene
Während AGENTS.md bzw. CLAUDE.md im Projektverzeichnis eben nur für dieses Projekt gilt, können Sie die gleichnamige Datei auch in speziellen Xcode-Verzeichnissen speichern. Die dort formulierten Regeln gelten dann für alle Projekte in Xcode, in denen Sie den jeweiligen Agenten zu Hilfe nehmen.
Die aktuelle KI-Integration sieht die folgenden beiden Verzeichnisse zur Konfiguration von Claude Agent bzw. Codex vor (Quelle):
~/Library/Developer/Xcode/CodingAssistant/codex
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig
Die dort gespeicherten Dateien werden — parallel zu eventuell ebenfalls vorhandenen gleichnamigen Dateien auf Projektebene — automatisch berücksichtigt, sobald Xcode Codex oder Claude Agent startet.
Vorsicht! Das
ClaudeAgentConfig-Verzeichnis gilt nicht, wenn Sie in Xcode Claude verwenden. Es wird nur von Claude Agent berücksichtigt. Diese verwirrende Differenzierung zwischen zwei fast gleichnamigen KI-Features hat mir anfangs eine Menge Zeit gekostet.
Systemweite AGENTS.md-Dateien sind also der ideale Ort, um Swift- bzw. Xcode-spezifische Anweisungen zu speichern, die nichts mit einem konkreten Projekt zu tun haben. Es ist empfehlenswert, den Coding-Agenten dort Hinweise zu geben, dass diese ausschließlich moderne Swift-Sprachmerkmale (z.B. Concurrency) und SwiftUI-Features nutzen sollen.
Warum ist das so wichtig? Sprachmodelle werden mit im Internet verfügbaren Informationen trainiert. Dort überwiegen aber veraltete Informationen, die sich auf ältere Swift/SwiftUI-Versionen beziehen. Deswegen ist der von KI-Sprachmodellen generierte Code oft sub-optimal. (Dass Apple den Coding-Agenten via MCP Zugriff auf die aktuelle Dokumentation gibt, hilft nicht viel. Die KI erkennt gar nicht die Notwendigkeit, dort nachzusehen.)
Es gibt im Internet mehrere Vorlagen für AGENTS.md/CLAUDE.md. Die beste stammt meiner Ansicht nach von Paul Hudson (Hacking with Swift):
https://github.com/twostraws/SwiftAgents/blob/main/AGENTS.md
Laden Sie die Datei herunter, und speichern Sie diese unter einem der beiden folgenden Pfade:
~/Library/Developer/Xcode/CodingAssistant/codex/AGENTS.md
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/CLAUDE.md
Lesenswert ist dazu auch Hudsons Blog-Artikel What to fix in AI-generated Swift code!
AGENTS.md bzw. CLAUDE.md auf Systemebene
Die Dateien .claude/CLAUDE.md bzw. .codex/AGENTS.md erfüllen die gleiche Funktion, aber auf Systemebene und losgelöst von Xcode. Dort durchgeführte Einstellungen gelten allerdings für ALLE Programmiersprachen. Insofern ist es keine gute Idee, hier Swift- oder Xcode-spezifische Anweisungen zu speichern.
Wenn die Dateien CLAUDE.md bzw. AGENTS.md auf mehreren Ebenen (System, Xcode, Projekt) existieren, werden alle Dateien berücksichtigt und kombiniert. Umso wichtiger ist es, die Dateien nicht unnötig aufzublähen.
Swift-spezifische Skills
Skills verfolgen die gleiche Idee wie AGENTS-Dateien, formulieren also Regeln im Markdown-Format. Aber während die AGENTS-Dateien immer berücksichtigt werden, werden Skills nur bei Bedarf ausgewertet. Beispielsweise kann ein Skill-Dateiset Refactoring-Regeln enthalten. Erst wenn Sie in einem Prompt explizit Refactoring erwähnen (manchmal müssen Sie ganz explizit auf den Skill hinweisen), werden die dort gespeicherten Zusatzregeln berücksichtigt. Skills können auch Anweisungen für den Aufruf externer Tools beinhalten. Das ist an dieser Stelle aber kein Thema.
In den letzten Monaten haben einige Blogger Skill-Sets für Swift und SwiftUI zusammengestellt (siehe die Links am Ende dieses Beitrags). Ich greife an dieser Stelle den besonders nützlichen Skill SwiftUI Pro heraus:
https://github.com/twostraws/SwiftUI-Agent-Skill
Dieser Skill ist dazu gedacht, um in vorhandenen SwiftUI-Projekten einen Code Review durchzuführen — wahlweise via Claude Code, Codex CLI oder Xcode. Das KI-Sprachmodell durchsucht den Code dann nach veraltetem Code und macht Verbesserungsvorschläge. Das funktioniert großartig!!
Ein konkretes Anwendungsbeispiel im Zusammenspiel mit Claude Code folgt gleich. Vorerst geht es aber um die Installation, bei der es mehrere Varianten gibt, je nachdem ob Sie den Skill in einer CLI (Claude Code, Codex CLI) oder direkt in Xcode nutzen möchten.
Beginnen wir mit der Installation für CLI-Tools: Dazu öffnen Sie ein Terminalfenster und wechseln in das Projektverzeichnis. (Das Installationskommando setzt Node.js voraus. Führen Sie gegebenenfalls vorher brew install node aus.)
cd my-swiftui-project
npx skills add https://github.com/twostraws/swiftui-agent-skill --skill swiftui-pro
Während der Installation werden Sie gefragt, welche KI-Tools/Agenten Sie verwenden (z.B. Antigravity, Claude Code, Codex, Cursor usw.). Das hat Einfluss auf den Installationsort. Viele KI-Tools berücksichtigen das Verzeichnis .agents/skills, aber manche Tools wollen ihr eigenes Verzeichnis (z.B. .agent/skills oder .claude/skills). Dort werden standardmäßig Links auf die Dateien in .agents eingerichtet.
Außerdem müssen Sie sich entscheiden, ob die Skills universell für alle Projekte gelten sollen (Installation relativ zum Home-Verzeichnis) oder nur für ein Projekt (Installation im Projekt-Verzeichnis). Vor allem wenn Sie auf Ihrem Rechner Projekte in verschiedenen Programmiersprachen entwickeln, ist die projektspezifische Installation sicherer.
Die Xcode-Installation ist leider etwas umständlicher. Ich gehe davon aus, dass Sie vorher eine CLI-Installation in ein Projektverzeichnis durchgeführt haben. Von dort kopieren Sie nun das gewünschte Skills-Unterverzeichnis in das passende Xcode-Verzeichnis:
# für Claude Code
mkdir -p ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills
cd my-swiftui-project
cp -a .claude/skills/swiftui-pro ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills
# für Codex
mkdir -p ~/Library/Developer/Xcode/CodingAssistant/codex/skills
cd my-swiftui-project
cp -a .agents/skills/swiftui-pro ~/Library/Developer/Xcode/CodingAssistant/codex/skills
Jetzt sollten Sie sich noch vergewissern, dass der neue Skill wirklich im KI-Agenten Ihrer Wahl innerhalb von Xcode verfügbar ist (hier für Claude Code).
Der Aufruf des Skills variiert je nach Coding-Agent:
- Claude Agent:
/swiftui-profunktioniert nicht. (Dieses Claude-Code-Kommando klappt nur in der CLI.) Vielmehr müssen Sie in Xcode einen Prompt formulieren, der so ähnlich wie diese Anweisung aussieht: »Use the SwiftUI Pro skill to look for problems in this project.« -
Codex:
$swiftui-pro
Anwendungsbeispiel mit Claude Code
Im Folgenden gehe ich davon aus, dass Sie mit Claude Code arbeiten. Nach dem Start vergewissern Sie sich mit dem Kommando /skills, dass Claude die Skill-Regeln swiftui-pro kennt. Den Code Audit starten Sie nun mit /swiftui-pro (bzw. in Codex mit $swiftui-pro).
cd my-swiftui-project
claude
> /skills
...
> /swiftui-pro
...
Summary
1. Accessibility (high): Multiple icon-only buttons throughout
(PlanTabView:66, SettingsTabView:159, CategoriesView:23/37) are invisible
to VoiceOver. The CategoryHeader uses onTapGesture instead of Button, also
problematic for VoiceOver.
2. Deprecated API (high): foregroundColor() used in 6+ locations should be
foregroundStyle(). cornerRadius() used in 3 locations should be
clipShape(.rect(cornerRadius:)). tabItem() should be the modern Tab
API. .autocapitalization() should be .textInputAutocapitalization(). Style
struct instances (PlainButtonStyle(), etc.) should use static member
syntax.
3. Code organization (medium): Multiple type definitions per file throughout
the view layer (PlanTabView has 3 types, SettingsTabView has 3,
EditItemView has 3, CategoriesView has 2). Each should be in its own
file. The itemsForEach method returning some View should be a dedicated
View struct.
4. Data flow (medium): Category class is @Observable but missing
@MainActor. @State var vm in ShoppingTabView, PlanTabView, and
CategoriesView is not marked private.
5. Modern Swift (low): Use Date.now over Date(), URL.documentsDirectory over
FileManager lookups, !items.isEmpty over items.count > 0, modern ISO 8601
date parsing, and the Tab enum pattern for tab selection.
The review is complete above. Would you like me to fix any of these issues?
Alle Probleme auf einmal zu beheben ist keine gute Idee. Besser gehen Sie schrittweise vor und erstellen nach jedem Fix und dem nachfolgenden Test Ihrer App Xcode einen Commit.
> fix foregroundColor()
Done. Replaced all .foregroundColor() with .foregroundStyle() across 3 files:
- ContentView.swift - 4 occurrences (debug overlay text colors)
- PlanTabView.swift - 2 occurrences (toggle button labels)
- SettingsTabView.swift - 3 occurrences (error text, warning text, sync time indicator)
> ! git commit -a -m 'fixed foregroundColor -> foregroundStyle'
Lesetipps
AGENT-Dateien und Skills bestehen aus Markdown-Dateien. Selbst wenn Sie keine KI-Tools verwenden wollen, lohnt sich die Lektüre dieser Regeldateien. Sie werden nirgendwo sonst so kompakte Regeln zur richtigen Swift/SwiftUI-Programmierung finden! Lesen Sie beispielsweise die Anweisungen zur richtigen Verwendung von Actors aus dem Concurrency-Skill von Paul Hudson.
Quellen/Links
Grundlagen zu AGENTS.md/CLAUDE.md/Skills
- https://agents.md
- https://developers.openai.com/codex/guides/agents-md
- https://code.claude.com/docs/en/features-overview
- https://support.claude.com/en/articles/12512176-what-are-skills
Agentic Coding mit Xcode
- https://kofler.info/xcode-26-3-kann-endlich-ki
- https://developer.apple.com/documentation/Xcode/setting-up-coding-intelligence#Customize-the-Codex-and-Claude-Agent-environments
- https://www.hackingwithswift.com/articles/281/what-to-fix-in-ai-generated-swift-code
- https://www.hackingwithswift.com/articles/282/swiftui-agent-skill-claude-codex-ai
- https://www.hackingwithswift.com/articles/283/how-to-install-and-use-ai-agent-skills-in-xcode
- https://developer.apple.com/documentation/xcode/giving-agentic-coding-tools-access-to-xcode
Für Swift optimierten AGENTS.md-Dateien und Skills von Paul Hudson
- https://github.com/twostraws/swiftagents (AGENTS.md)
- https://github.com/twostraws/SwiftUI-Agent-Skill (Swift-Basics und SwiftUI)
- https://github.com/twostraws/swiftdata-agent-skill (SwiftData)
- https://github.com/twostraws/swift-concurrency-agent-skill (Concurrency)
- https://github.com/twostraws/Swift-Testing-Agent-Skill (Unit-Tests)
Ähnliche Dateien/Skills von anderen Entwicklern
- https://github.com/AvdLee/SwiftUI-Agent-Skill
- https://github.com/AvdLee/Swift-Concurrency-Agent-Skill
Videos
- https://www.youtube.com/watch?v=QdpaI_j0FRU (Stewart Lynch)
- https://www.youtube.com/live/sc6pvW6vQzA (Paul Hudson)
