Apple führt das Problem, dass mit Xcode 27 gelieferte Agent Skills möglicherweise nicht in Codex erscheinen, in den Xcode-27-Release-Notes als bekanntes Problem mit Lösungshinweis. Die Konsequenz für Ihre Fehlersuche: Prüfen Sie zuerst, ob xcrun tatsächlich die Xcode-27-Toolchain verwendet, und exportieren Sie die Skills anschließend nach Apples Anleitung in das für Codex vorgesehene Verzeichnis. Ein erfolgreicher Export beweist noch nicht, dass Codex die Dateien gefunden oder ihre Anweisungen befolgt hat.
Dieser Leitfaden richtet sich an Entwickler, die Codex für Swift- oder SwiftUI-Projekte nutzen und Apples Xcode-Anweisungen einbinden möchten.
Er ist ebenso für DevOps-Verantwortliche gedacht, die mehrere Xcode-Versionen auf einem per SSH verwalteten Remote Mac pflegen.
Plattformverantwortliche finden hier die Abgrenzung zwischen persönlichem Skill-Verzeichnis und gemeinsam verwalteten Projektanweisungen.
Zuletzt aktualisiert am 10.10.2026. Die Prüfschritte stützen sich auf Apples Xcode-27-Release-Notes, Apples Dokumentation zu Xcode und Kommandozeilenwerkzeugen sowie die Codex-Dokumentation zu Skills. Da sich Pfade und Erkennungsregeln ändern können, gleichen Sie die Anweisungen vor einem produktiven Rollout mit den jeweils aktuellen Dokumenten ab.
SECTION 01 Die drei Zustände getrennt prüfen
Bei diesem Fehler werden oft drei verschiedene Ergebnisse als dasselbe behandelt: Die Skills wurden exportiert, die Dateien liegen im erwarteten Verzeichnis, und Codex hat die Skills erkannt und verwendet. Nur der letzte Zustand löst das eigentliche Problem. Ein erfolgreicher Befehl kann die ersten beiden belegen, aber nicht automatisch den dritten.
Apples Entwicklerdemonstration behandelt den Export von Agent Skills aus Xcode. Für die Diagnose ist entscheidend, diese Funktion nicht mit einer allgemeinen Zusage zu verwechseln, dass jede Codex-Version jedes Exportziel automatisch durchsucht. Die Apple-Demonstration zum Export von Agent Skills erklärt den Xcode-seitigen Ablauf; die tatsächlichen Regeln zur Skill-Erkennung müssen Sie zusätzlich anhand der Codex-Dokumentation zu Skills und Ihrer installierten Codex-Version prüfen.
Warum erscheinen Xcode 27 Agent Skills nicht in Codex? Häufig liegt die Ursache nicht an den Skill-Inhalten, sondern an einer nicht passenden aktiven Toolchain, einem abweichenden Exportpfad oder daran, dass Codex das gewählte Verzeichnis nicht als Skill-Quelle behandelt. Prüfen Sie diese Ursachen nacheinander, statt den Export wiederholt auszuführen oder Dateien vorschnell zu überschreiben.
| Prüfschritt | Was Sie belegen | Was der Befund bedeutet |
|---|---|---|
| Aktive Toolchain | Ausgabe von xcode-select -p und xcodebuild -version |
Zeigt, welches Xcode für die Kommandozeile ausgewählt ist |
| Export | Befehl, Ausgabe und Rückgabestatus | Belegt, ob der Exportbefehl abgeschlossen wurde |
| Zielverzeichnis | Vorhandene Ordner und Skill-Dateien | Belegt, ob Dateien am gewählten Ziel angekommen sind |
| Codex-Erkennung | Skill-Verfügbarkeit in der verwendeten Codex-Umgebung | Belegt, ob Codex diese Quelle tatsächlich berücksichtigt |
| Aufgabenprüfung | Ergebnis einer begrenzten Swift-Aufgabe | Zeigt, ob die geladene Anleitung das Verhalten beeinflusst |
Die Tabelle ist bewusst keine Erfolgsgarantie: Jeder Schritt liefert einen eigenen Beleg. Fällt eine Prüfung durch, arbeiten Sie an genau dieser Stelle weiter. Ändern Sie nicht zugleich Toolchain, Verzeichnis und Projektkonfiguration, weil Sie danach nicht mehr erkennen können, welche Änderung den Befund verursacht hat.
SECTION 02 Zuerst die aktive Xcode-Toolchain verifizieren
Wie prüfen Sie, ob xcrun Xcode 27 verwendet? Lesen Sie den ausgewählten Entwicklerpfad aus und gleichen Sie ihn mit der Ausgabe von Xcode ab. Apples Dokumentation beschreibt die Auswahl der Kommandozeilenwerkzeuge und den Zusammenhang zwischen ausgewähltem Entwicklerverzeichnis und den aufgerufenen Werkzeugen; die Apple-Anleitung zu den Kommandozeilenwerkzeugen und Apples Technote zu Xcode-Builds über die Kommandozeile sind die maßgeblichen Referenzen für diese Prüfung.
Führen Sie die Befehle in derselben Sitzung aus, in der Sie später exportieren:
xcode-select -p
xcodebuild -version
xcrun --find swift
xcrun agent skills export --help
xcode-select -p gibt den für die Kommandozeile gewählten Entwicklerpfad aus. xcodebuild -version hilft Ihnen zu kontrollieren, welche Xcode-Installation der Build-Aufruf verwendet; xcrun --find swift zeigt, wo das aufgelöste Swift-Werkzeug liegt. Der Aufruf der Hilfe prüft, ob das Skill-Unterkommando in der aktuell gewählten Umgebung verfügbar ist und welche Optionen diese Installation dokumentiert. Behandeln Sie eine einzelne Ausgabe nicht als Beweis für alle Xcode-Versionen oder Installationsarten.
Wenn der Entwicklerpfad auf eine andere Installation verweist, wählen Sie die gewünschte Xcode-27-Installation aus. Ersetzen Sie den Beispielpfad durch den tatsächlichen Installationspfad Ihres Systems:
sudo xcode-select --switch /Applications/Xcode-27.app/Contents/Developer
Prüfen Sie danach xcode-select -p, xcodebuild -version und xcrun --find swift erneut. Der Pfad /Applications/Xcode-27.app ist hier ein Beispiel, kein von Apple für jede Installation vorgeschriebener Dateiname. Die Systemanforderungen für Xcode helfen Ihnen außerdem zu prüfen, ob die vorhandene macOS-Version für die eingesetzte Xcode-Version geeignet ist. Auf einem Remote Mac mit parallel installierten Xcode-Versionen sollten Sie den tatsächlichen App-Pfad dokumentieren, statt aus dem Namen einer Desktop-Verknüpfung auf die aktive Toolchain zu schließen.
Ändern Sie die aktive Toolchain nicht nebenbei auf einem gemeinsam genutzten Build-Rechner. Halten Sie vorher fest, welcher Entwicklerpfad aktiv ist und welche Jobs davon abhängen; stimmen Sie den Wechsel mit den Verantwortlichen ab und stellen Sie bei unerwarteten Nebenwirkungen die dokumentierte vorherige Auswahl wieder her.
SECTION 03 Exportpfad und Codex-Erkennung separat kontrollieren
Wenn die richtige Toolchain aktiv ist, exportieren Sie mit dem von Apple angegebenen Verfahren. Apples Release-Notes nennen als Abhilfe die Auswahl der Xcode-27-Toolchain und den Export in das Codex-Skill-Verzeichnis. Verwenden Sie für den konkreten Befehl und das Ziel den Wortlaut der Xcode-27-Release-Notes; prüfen Sie vor dem Export zusätzlich mit xcrun agent skills export --help, ob Ihre installierte Fassung dieselbe Option unterstützt.
Für den dort genannten Codex-Pfad lautet die Befehlsform:
xcrun agent skills export --path ~/.codex/skills
Führen Sie diesen Aufruf im Konto aus, dessen Skills Codex später verwenden soll. Ein Export unter einem anderen Benutzerkonto kann Dateien an einem anderen persönlichen Ort ablegen. Auf einem per SSH verwalteten Mac ist daher nicht nur der Host, sondern auch die angemeldete Benutzeridentität relevant. Kontrollieren Sie vor und nach dem Export das Ziel, zum Beispiel mit:
printf '%s\n' "$HOME"
ls -la "$HOME/.codex"
find "$HOME/.codex/skills" -maxdepth 3 -name SKILL.md -print
Falls das Ziel nicht existiert oder keine Skill-Dateien enthält, speichern Sie die genaue Befehlsausgabe und den Rückgabestatus. Wiederholen Sie nicht blind denselben Befehl: Zuerst muss klar sein, ob das Problem in der gewählten Toolchain, der Exportoption, der Berechtigung oder dem Zielpfad liegt. Wenn Dateien vorhanden sind, ist der Export belegt, aber nicht die Erkennung durch Codex.
Wie exportieren Sie Apples Agent Skills in das Codex-Verzeichnis? Wählen Sie zuerst die passende Xcode-Toolchain, gleichen Sie die unterstützte Befehlsform mit Apples Release-Notes und der lokalen Hilfe ab und verwenden Sie dann das dort dokumentierte Ziel. Halten Sie den vollständigen Pfad und die Benutzeridentität fest. Codex kann je nach aktueller Dokumentation und verwendeter Version eigene Regeln für Skill-Verzeichnisse haben; deshalb vergleichen Sie den Exportpfad mit den Codex-Regeln zur Ablage und Nutzung von Skills, bevor Sie aus vorhandenen Dateien auf eine erfolgreiche Erkennung schließen.
In Teams sollten Sie persönliche Skills außerdem nicht mit gemeinsam versionierten Projektanweisungen vermischen. Apples Exportziel kann ein benutzerspezifisches Verzeichnis sein; eine Projektkonfiguration muss dagegen für Teammitglieder nachvollziehbar und über den vorgesehenen Repository-Prozess verwaltbar sein. Ob ein Skill im Projektkontext erkannt wird, prüfen Sie anhand der aktuellen Codex-Dokumentation und in der tatsächlichen Arbeitsumgebung. Ein Pfad, der auf Ihrem Konto funktioniert, ist keine Zusage, dass er auf anderen Konten oder in CI denselben Effekt hat.
SECTION 04 Bei mehreren Xcode-Installationen nichts unkontrolliert überschreiben
Bei mehreren Toolchains entstehen zwei Risiken: Ein Export kann mit der falschen Xcode-Version laufen, oder er kann vorhandene Dateien an einem gemeinsam genutzten Ziel beeinflussen. Prüfen Sie deshalb vor jedem Schreibvorgang den aktiven Entwicklerpfad, das aufgelöste Benutzerkonto und das genaue Exportziel. Wenn Sie bereits Skill-Dateien oder eigene Anweisungen an diesem Ort verwalten, sichern oder versionieren Sie sie vor einer Änderung.
Die Apple-Dokumentation ist die Referenz dafür, welche Exportoptionen das jeweilige Xcode unterstützt. Verwenden Sie Optionen, die ein vorhandenes Ziel ersetzen oder verändern könnten, nur dann, wenn ihre Wirkung durch die aktuelle Hilfe oder Apples Dokumentation belegt ist. Erfinden Sie keine Schalter aus Beispielen anderer Werkzeugversionen. Eine sichere Rückfallmöglichkeit besteht darin, zuerst den bisherigen Verzeichnisinhalt zu erfassen und eine separate, kontrollierte Sicherung anzulegen, bevor Sie einen Export mit potenziell überschreibendem Verhalten ausführen.
Wenn ein Team einen zentralen Skill-Satz benötigt, entscheiden Sie bewusst zwischen persönlichem Export und gemeinsam verwalteter Konfiguration. Prüfen Sie bei der gemeinsamen Variante, ob Geheimnisse, lokale Pfade oder kontospezifische Anweisungen in das Repository geraten würden. Für die Einordnung von Agent-Anweisungen und Zugriffstrennung können Sie ergänzend den Beitrag über Xcode-Agent-Integration und Isolation in Unternehmen heranziehen. Die technische Ablageentscheidung bleibt jedoch von der jeweiligen Codex-Version und den geltenden Teamrichtlinien abhängig.
SECTION 05 Reparatur mit einer realen Swift-Aufgabe abnehmen
Ein Verzeichnisfund ist kein Funktionstest. Verwenden Sie eine Aufgabe, bei der die exportierte Anleitung tatsächlich relevant sein sollte, aber begrenzen Sie den Umfang so, dass Sie das Ergebnis prüfen können. Geeignet ist etwa eine kleine Swift- oder SwiftUI-Änderung in einem kontrollierten Arbeitszweig. Formulieren Sie die Aufgabe so, dass Codex eine konkrete, überprüfbare Arbeit ausführt, und vergleichen Sie anschließend seine Schritte und Änderungen mit den Anweisungen des Skills.
Gehen Sie in dieser Reihenfolge vor:
- Ausgangszustand notieren. Halten Sie Xcode-Version, Ausgabe von
xcode-select -p, Benutzerkonto und verwendete Codex-Version fest. Bewahren Sie die Angaben zusammen mit dem Fehlerprotokoll auf, nicht nur in einer flüchtigen SSH-Sitzung. - Befehl und Ziel bestätigen. Prüfen Sie die lokale Hilfe für
xcrun agent skills exportund vergleichen Sie das vorgesehene Ziel mit Apples aktueller Anleitung. Verändern Sie nicht gleichzeitig die persönliche Ablage und die Projektkonfiguration. - Export kontrolliert ausführen. Verwenden Sie die von Apple dokumentierte Exportform für Ihre Installation. Sichern Sie die Ausgabe und kontrollieren Sie den Rückgabestatus, ohne diesen als Nachweis einer Codex-Erkennung zu behandeln.
- Dateien am Ziel untersuchen. Prüfen Sie Verzeichnisstruktur und Skill-Dateien. Stimmen Sie festgestellte Dateinamen und Struktur mit der Codex-Dokumentation ab; ändern Sie keine generierten Inhalte, bevor Sie eine unveränderte Sicherung haben.
- Codex neu prüfen. Verwenden Sie die in Ihrer installierten Codex-Version dokumentierte Methode, um die verfügbaren Skills oder deren Erkennung zu kontrollieren. Behauptet die Oberfläche oder das Werkzeug keine Erkennung, obwohl Dateien vorhanden sind, ist das ein eigener Befund und kein Grund, den Export als erfolgreich abzuhaken.
- Begrenzte Swift-Aufgabe ausführen. Bitten Sie Codex um eine klar abgrenzbare Änderung, die zur dokumentierten Skill-Anleitung passt. Prüfen Sie sowohl die resultierende Änderung als auch, ob Codex die relevante Anleitung erkennbar berücksichtigt hat. Ein plausibles Ergebnis allein beweist noch nicht, dass genau dieser Skill geladen wurde.
- Ergebnis reproduzierbar festhalten. Dokumentieren Sie Xcode-Version, aktiven Toolchain-Pfad, Exportziel, Codex-Version, Erkennungsbefund und Testergebnis. Bei weiterem Fehler sichern Sie diese Belege und stoppen Sie wiederholte Exporte, bis die Ursache eingegrenzt ist.
Was tun Sie, wenn der Export auf einem Remote Mac erfolgreich war, Codex aber weiterhin keinen Skill verwendet? Prüfen Sie zunächst, ob Codex unter demselben Benutzerkonto läuft, in dem die Dateien liegen, und ob die aktuelle Codex-Dokumentation dieses Verzeichnis als gültige Quelle aufführt. Danach trennen Sie Sichtbarkeit von tatsächlicher Anwendung: Wird der Skill gar nicht erkannt, liegt der Schwerpunkt auf Pfad und Entdeckungsregeln; wird er erkannt, aber bei der Aufgabe nicht berücksichtigt, untersuchen Sie Aufgabenbezug und Anweisungen. Apple bestätigt den Xcode-seitigen Exporthinweis, nicht das Ergebnis jeder Kombination aus Remote-Umgebung und Codex-Version.
SECTION 06 Entscheidung nach Befund statt wiederholtem Export
Nach den Prüfungen sollte feststehen, an welcher Grenze der Ablauf scheitert. Die folgenden Fälle führen zu unterschiedlichen nächsten Schritten:
xcrunfindet den Skill-Befehl nicht: Kontrollieren Sie den aktiven Entwicklerpfad und die lokal verfügbare Xcode-Installation. Erst wenn der erwartete Toolchain-Kontext aktiv ist, führen Sie den Export erneut aus.- Der Befehl läuft, aber am Ziel fehlen Dateien: Prüfen Sie Konto, Schreibrechte, Pfadangabe und den tatsächlichen Rückgabestatus. Sichern Sie die Ausgabe, bevor Sie einen weiteren Schreibversuch starten.
- Dateien liegen am Ziel, Codex erkennt sie nicht: Vergleichen Sie den Ordner mit den aktuellen Codex-Regeln. Ein von Apple verwendetes Exportziel und eine von Codex unterstützte Skill-Quelle müssen nicht allein deshalb identisch sein, weil der Ordnername Codex enthält.
- Codex erkennt die Dateien, folgt ihnen aber nicht erkennbar: Führen Sie eine eng begrenzte Aufgabe mit klarer Beziehung zum Skill durch und dokumentieren Sie das Verhalten. Behaupten Sie keine erfolgreiche Reparatur ohne diesen Test.
- Die Teamkonfiguration bleibt uneindeutig: Trennen Sie Benutzer-Skills und versionierte Projektanweisungen. Legen Sie fest, wer Änderungen prüft und wie ein fehlerhafter Export zurückgenommen wird.
Wenn Sie an dieser Stelle noch keine verfügbare Xcode-27-Umgebung haben, vergleichen Sie zuerst, ob eine eigene Mac-Installation oder eine temporär nutzbare Remote-Umgebung für Ihren Test besser passt. Eine lokale Anschaffung bindet Kapital und muss von Ihnen gewartet werden; eine vorhandene Linux-Umgebung stellt die benötigte Apple-Toolchain nicht bereit; eine virtuelle macOS-Umgebung ist kein Ersatz für eine Prüfung, die eine unterstützte reale Mac-Umgebung voraussetzt. Für einen einmaligen Fehlernachweis kann ein gemieteter Remote Mac von VPSNIX die flexiblere Wahl sein, wenn Sie eine zugängliche macOS-Umgebung benötigen, ohne dafür dauerhaft eigene Hardware vorzuhalten. Sehen Sie sich die VPSNIX-Mietoptionen für Mac-Umgebungen an und prüfen Sie vor der Entscheidung, ob Zugriffsweg, Laufzeit und benötigte Xcode-Version zu Ihrem Test passen.