Kurzentscheidung: Dauerhaft geltende, kurze Regeln gehören in AGENTS.md; umfangreiche Abläufe für bestimmte Aufgaben gehören als OpenHands Skills in eine SKILL.md. Xcode-Builds, Signierung und Geräteeinsatz dürfen jedoch nie allein durch diese Hinweise als bestanden gelten, sondern benötigen eine unabhängige Mac-Abnahme.

Diese Einordnung gilt besonders dann, wenn Sie ein iOS-Repository mit mehreren Rollen betreiben: Maintainer benötigen einen stabilen gemeinsamen Rahmen, Entwickler brauchen bei Bedarf Swift- und Xcode-Wissen, während Plattform- und Sicherheitsteams die geladenen Ressourcen und Berechtigungen kontrollieren müssen.

Zuletzt aktualisiert: 06.09.2026. Die Aussagen wurden gegen die in diesem Beitrag verlinkte OpenHands- und Apple-Dokumentation sowie gegen die beschriebene Prüfmethodik abgeglichen.

Die Zuständigkeit entscheidet, nicht die Dateiendung

Die häufigste Fehlentscheidung entsteht, wenn AGENTS.md und Skills nach Dateiformat statt nach Verantwortlichkeit ausgewählt werden. Beide können Regeln für einen Coding Agent sichtbar machen, erfüllen aber nicht dieselbe Funktion.

AGENTS.md sollte den unvermeidbaren gemeinsamen Nenner beschreiben:

  • Wofür das Repository dient und welche Teile nicht verändert werden dürfen.
  • Wo App-Projekt, Packages, Tests und Dokumentation liegen.
  • Welche grundlegenden Installations- oder Prüfkommandos für alle Änderungen gelten.
  • Welche allgemeinen CI-Sperren vor einem Merge erfüllt sein müssen.
  • Welche Dateien besonders geschützt sind und wer Änderungen daran freigibt.

Diese Datei muss kurz genug bleiben, damit ein Agent sie bei jeder relevanten Arbeit zuverlässig berücksichtigen kann. Eine vollständige Anleitung für Zertifikate, Simulatorfehler, Testpläne und UI-Diagnose gehört dort nicht hinein. Je mehr Sonderfälle Sie in den permanenten Kontext laden, desto schwieriger wird es, eine Regelverletzung eindeutig zu erkennen.

OpenHands Skills übernehmen dagegen Wissen, das nur bei einem passenden Auftrag relevant ist. Ein Skill kann beispielsweise erklären, wie ein bestimmtes Swift-Modul getestet wird, welche Testziele zu einer Änderung gehören oder wie ein bekanntes Xcode-Fehlerbild untersucht wird. Die Beschreibung des Skills muss dabei so konkret sein, dass der Agent erkennen kann, wann er ihn laden soll.

Die aktuelle OpenHands-Dokumentation zu Skills führt Skills als aktuelle Bezeichnung. Bestimmte Microagents-Pfade werden dort als ältere oder nicht mehr empfohlene Form behandelt. Daraus folgt aber nicht, dass jede bestehende Installation ohne Prüfung umgebaut werden sollte. Entscheidend ist der tatsächlich geladene Inhalt und die Fähigkeit, bei einem Übergang denselben Auftrag reproduzierbar zu prüfen.

Rollenmodell für iOS-Repositorys

Repository-Maintainer: den unveränderlichen Kern pflegen

Der Maintainer sollte AGENTS.md aus überprüfbaren Repository-Quellen ableiten, nicht aus einer frei erfundenen Idealbeschreibung. Die Verzeichnisstruktur, vorhandene Workflow-Dateien, Package-Konfigurationen und bestehende CI-Sperren liefern dafür belastbare Hinweise.

Ein brauchbarer Kern enthält nur Regeln, die auch nach einer Xcode-Aktualisierung oder einer Moduländerung noch gelten. Dazu gehören etwa der zulässige Projektpfad, das erwartete Arbeitsverzeichnis und die Pflicht, Tests nicht als bestanden zu melden, wenn lediglich ein Befehl vorbereitet wurde.

Vermeiden Sie Formulierungen wie „arbeite sauber“ oder „prüfe alles gründlich“. Besser ist eine überprüfbare Anweisung: Der Agent muss die geänderten Dateien nennen, den verwendeten Build- oder Testpfad ausweisen und unbekannte Änderungen vor dem Commit melden. So wird aus einer Stilpräferenz eine nachvollziehbare Übergaberegel.

Mobile Entwickler: iOS-Wissen nur bei Bedarf laden

Der iOS-Skill sollte den Arbeitsablauf eines konkreten Teams unterstützen, ohne den Inhalt von AGENTS.md zu duplizieren. Sinnvolle Abschnitte betreffen Swift-Konventionen, den Einstieg in das Projekt, relevante Testziele, typische Fehlerbilder und die Entscheidung, wann ein Auftrag an die Mac-Abnahme übergeben werden muss.

Xcode-Version, Simulatorstatus, Scheme-Namen und konkrete Build-Kommandos dürfen nicht aus einer veralteten Beispielanleitung stammen. Sie müssen aus dem tatsächlichen Projekt, den Workflow-Dateien oder der CI-Konfiguration überprüft werden. Apple beschreibt in der Dokumentation zum Anpassen von Build-Schemes, dass Schemes die Auswahl von Build- und Testaktionen beeinflussen. Das ist genau der Grund, warum ein statischer Skill-Text keinen erfolgreichen Lauf beweist.

Ein Skill sollte außerdem zwischen Anleitung und Ergebnis unterscheiden. „Führe den Testplan aus“ ist eine Handlungsanweisung. „Der Testplan wurde erfolgreich ausgeführt“ ist eine Behauptung, die nur ein Protokoll oder eine vergleichbare Abnahme belegen kann.

Plattformteam: Ladepfade und Wiederverwendung kontrollieren

Plattformverantwortliche müssen nachvollziehen können, welche Regel aus welchem Ort stammt. Projektregeln, benutzerbezogene Skills und ältere Verzeichnisse dürfen nicht stillschweigend denselben Namen verwenden, wenn dadurch eine unsichtbare Überschreibung entsteht.

Für gemeinsam genutzte Skills sollten Sie mindestens Folgendes dokumentieren:

  • Version und Änderungsdatum.
  • Verantwortlicher Eigentümer.
  • Geltungsbereich und erwartete Auslöser.
  • Abhängigkeiten zu Skripten, Referenzen oder Werkzeugen.
  • Rückfallpfad, falls eine neue Fassung nicht geladen oder nicht unterstützt wird.

Die SDK-Anleitung für Skills ist für die technische Struktur hilfreich. Sie ersetzt aber nicht den Test in Ihrem Repository. Während der Migration aus älteren Microagents-Strukturen sollten Sie denselben risikoarmen Auftrag mit der alten und der neuen Anordnung ausführen. Verglichen werden nicht nur die Enddateien, sondern auch geladene Hinweise, verwendete Werkzeuge, ausgelassene Prüfungen und die erzeugte Übergabe.

Achtung: Ein gleichlautender Dateiname ist kein Beweis für gleiche Priorität. Wenn zwei Regeln scheinbar dieselbe Aufgabe beschreiben, dokumentieren Sie die effektive Ladequelle und entfernen Sie die Mehrdeutigkeit, statt auf die vermutete Reihenfolge zu vertrauen.

Die iOS-Aufteilung lässt sich an vier Prüfentscheidungen festmachen

Die folgende Gegenüberstellung ist kein starres Dateischema, sondern eine Entscheidungshilfe für die Verantwortlichkeiten:

In AGENTS.md einordnen, wenn …

  • die Regel bei praktisch jeder Änderung gilt;
  • sie kurz und ohne ausführliche Diagnose erklärbar ist;
  • sie aus Repository-Dateien oder dem allgemeinen CI-Vertrag hervorgeht;
  • ein Verstoß unabhängig vom verwendeten Framework verhindert werden soll.

In einen OpenHands Skill einordnen, wenn …

  • die Information nur bei einem bestimmten Framework, Modul oder Auftrag gebraucht wird;
  • sie mehrere Schritte, Beispiele oder Fehlerpfade umfasst;
  • sie sich mit der Xcode- oder Projektkonfiguration ändern kann;
  • der Agent anhand einer klaren Beschreibung entscheiden kann, wann sie relevant ist.

Außerhalb beider Regeltypen als Mac-Abnahme behandeln, wenn …

  • ein echter Xcode-Build erforderlich ist;
  • Simulator- oder Gerätedaten eine Rolle spielen;
  • Signierung, Schlüsselbund, Profile oder Veröffentlichungsrechte betroffen sind;
  • das Ergebnis von macOS, Hardwarezustand oder geschützten Zugangsdaten abhängt.

Die redaktionelle Bewertung fällt deshalb dreigeteilt aus:

  • AGENTS.md für dauerhafte Basisregeln: 5 von 5 – höchste Sichtbarkeit, geringe Komplexität, gut aus Repository und CI ableitbar.
  • Skills für aufgabenbezogenes iOS-Wissen: 5 von 5 – gute Trennung von Kontext und progressive Einblendung, sofern Trigger und Eigentümer klar sind.
  • Regeldateien als Abnahmeersatz: 1 von 5 – Hinweise können einen Ablauf strukturieren, aber weder Build, Signierung noch Gerätetest ausführen und belegen.

Diese Bewertung ist eine redaktionelle Entscheidungshilfe, keine Leistungs- oder Kompatibilitätsmessung.

Sicherheitsprüfung für Skills und ihre Ressourcen

Ein Skill endet nicht bei SKILL.md. Wenn er ein Skript startet, Referenzdateien einliest oder ein MCP-Werkzeug verwendet, erweitert sich die Vertrauensgrenze. Deshalb muss das Sicherheitsteam die ausführbaren Bestandteile genauso prüfen wie die Beschreibung.

Prüfen Sie mindestens:

  1. Welche Dateien ein Skript lesen, ändern oder löschen darf.
  2. Ob es Inhalte aus dem Netzwerk übernimmt oder Befehle dynamisch zusammensetzt.
  3. Ob Umgebungsvariablen, Schlüsselbunddaten oder Signierungsdateien erreichbar sind.
  4. Welche MCP-Werkzeuge geladen werden und ob sie Schreibzugriff besitzen.
  5. Ob Pfade außerhalb des Repositorys angesprochen werden.
  6. Ob ein absichtlich fehlerhafter oder verbotener Auftrag zuverlässig blockiert wird.
  7. Ob Laufprotokolle die tatsächliche Ausführung und nicht nur die Absicht zeigen.

Die OpenHands-Dokumentation zur SDK-Skill-Architektur sollte dabei gemeinsam mit der lokalen Konfiguration gelesen werden. Ein generischer Skill kann technisch korrekt beschrieben sein, aber in Ihrer Umgebung durch zusätzliche Werkzeuge deutlich größere Rechte erhalten.

Auch Hooks sind nicht automatisch eine Sicherheitsgrenze. Die OpenHands-Dokumentation zu Hooks zeigt, dass sie in Abläufe eingreifen können. Für ein iOS-Repository müssen Sie deshalb unterscheiden: Eine Regel informiert den Agent, ein Hook kann eine Aktion beeinflussen, und eine isolierte Mac-Abnahme entscheidet, ob das konkrete Artefakt akzeptiert wird.

Die Mac-Abnahme muss ein eigenes Übergabepaket erhalten

Wenn OpenHands Code ändert, sollte die Übergabe an die zuständige Mac-Umgebung nicht aus dem Satz „Tests erfolgreich“ bestehen. Der Empfänger benötigt ein prüfbares Paket mit:

  • Patch oder Commit-Referenz;
  • Liste der geänderten Dateien;
  • Änderungen an Abhängigkeiten und Build-Einstellungen;
  • verwendetes Scheme oder Testziel;
  • offene Annahmen und nicht ausgeführte Tests;
  • Hinweise zu erforderlichen Signierungs- oder Gerätezugriffen;
  • erwarteten Blockierbedingungen.

Die Ausführung sollte anschließend nach Risiko getrennt werden. Ein lokaler Build ist nicht dasselbe wie ein Simulator-Test; ein Simulator-Test ist nicht dasselbe wie ein signiertes Archiv. Apple beschreibt das Bauen und Starten einer App in Xcode und die Ausführung sowie Interpretation von Tests als getrennte Arbeitsbereiche. Ihre Abnahmeregel sollte diese Trennung beibehalten.

Ein mögliches Freigabemodell lautet:

  • Niedriges Risiko: Quelltextänderung ohne Abhängigkeit oder Signierung; Build und passende Tests auf dem Mac.
  • Mittleres Risiko: Projektdateien, Packages, Testpläne oder Simulatorverhalten; zusätzlich Prüfung der betroffenen Schemes und Testprotokolle.
  • Hohes Risiko: Signierung, Gerätezugriff, Veröffentlichung oder Änderungen an sensiblen Pfaden; gesonderte Berechtigung und nachvollziehbare Freigabe.

Die entscheidende Bedingung lautet: Der Merge hängt von den Belegen ab, nicht von der Selbstauskunft des Agents.

Erfahrung: Wenn der lokale Mac die Xcode-Abnahme nicht zuverlässig und wiederholbar übernehmen kann, ist ein klar begrenzter entfernter Mac-Arbeitsbereich oft besser als ein Regelwerk, das einen nicht vorhandenen Geräte- oder Signierungszugriff nur sprachlich simuliert.

FAQ: Migration, Xcode und Ressourcen

OpenHands Skills oder AGENTS.md: Was gehört wohin?

Die dauerhafte Repository-Verfassung gehört in AGENTS.md, die aufgabenbezogene Ausführung in Skills. Schreiben Sie die Installationsgrundlagen und allgemeinen CI-Sperren in die Basisdatei, aber verschieben Sie ausführliche Swift-, Framework- und Xcode-Diagnosen in einen Skill. Beide Ebenen sollten sich ergänzen, nicht dieselben Regeln mit leicht abweichender Formulierung wiederholen.

Ist eine sofortige Migration von OpenHands Microagents erforderlich?

Nein. Die offizielle Benennung hat sich in Richtung Skills entwickelt, und einzelne alte Pfade gelten als überholt oder nicht mehr bevorzugt. Eine sichere Migration beginnt trotzdem mit einer Bestandsaufnahme: Welche Dateien werden tatsächlich geladen, welche Regel gewinnt bei Konflikten und welches Ergebnis erzeugt ein kontrollierter Auftrag? Bis dieser Vergleich abgeschlossen ist, bleibt ein getesteter Rückfallpfad erhalten.

Soll der Xcode-Befehl in die permanente Regeldatei?

Der allgemeine Einstieg kann dort stehen, wenn er für das gesamte Repository stabil ist. Konkrete Simulatorziele, Scheme-Auswahl, Testpläne und Fehlerbehebung gehören in den iOS-Skill, weil sie sich schneller ändern und nur bestimmte Aufgaben betreffen. Das Kommando muss aus einer realen Projekt- oder CI-Quelle stammen. Der ausgeführte Befehl und sein Ergebnis werden anschließend separat auf dem Mac protokolliert.

Können Skills Skripte und Referenzen mitbringen?

Ja, aber dadurch wird der Skill zu mehr als einer Textanweisung. Prüfen Sie die mitgelieferten Skripte, ihre Dateirechte, dynamische Eingaben, Netzwerkverbindungen, MCP-Werkzeuge und erreichbaren Geheimnisse. Führen Sie außerdem einen Blockiertest aus, der einen verbotenen Pfad oder eine nicht erlaubte Aktion absichtlich anfordert. Ohne Laufprotokoll bleibt die Sicherheitsbewertung unvollständig.

Prüfliste für die erste risikoarme Einführung

Nutzen Sie diese Liste, bevor Sie Regeln in einem produktiven iOS-Repository als verbindlich behandeln:

  • [ ] Zweck, Verzeichnisstruktur und allgemeine Merge-Sperren in AGENTS.md auf kurze, überprüfbare Aussagen reduzieren.
  • [ ] Jede ausführliche Swift- oder Xcode-Anleitung einem klar benannten Skill zuordnen.
  • [ ] Für jeden Skill eine Beschreibung formulieren, die den passenden Aufgabentyp und den Auslöser erkennen lässt.
  • [ ] Xcode-Version, Scheme, Testziel und Build-Befehl aus dem echten Repository oder der CI-Konfiguration verifizieren.
  • [ ] Doppelte Regeln zwischen AGENTS.md, Skills und alten Microagents-Pfaden entfernen oder ausdrücklich als Übergang markieren.
  • [ ] Eigentümer, Version, Änderungsprüfung und Rückfallpfad für gemeinsam genutzte Skills dokumentieren.
  • [ ] Skripte, Referenzen, MCP-Werkzeuge und sensible Pfade durch das Sicherheitsteam prüfen lassen.
  • [ ] Einen risikoarmen iOS-Auftrag mit identischem Ausgangspunkt in der alten und neuen Struktur vergleichen.
  • [ ] Patch, Commit, Abhängigkeitsänderungen und offene Tests an die Mac-Abnahme übergeben.
  • [ ] Build, Simulator- oder Gerätetest, Signierung und Veröffentlichung als getrennte Nachweise erfassen.
  • [ ] Erst nach sichtbaren Protokollen und bestandenen Blockiertests eine Merge-Entscheidung treffen.

Für die Teamdokumentation können Sie zusätzlich die Datenschutzinformationen von SSHMac heranziehen, wenn bei einem entfernten Arbeitsbereich Fragen zu Zugangsdaten, Protokollen oder personenbezogenen Entwicklungsdaten entstehen. Bei organisatorischen Fragen zur Umgebung steht außerdem das Hilfe-Zentrum von SSHMac als Anlaufstelle zur Verfügung.

Die passende Infrastruktur folgt erst nach der Regelprüfung

Für ein kleines Repository mit lokal verfügbarem Mac genügt häufig ein sauberer AGENTS.md-Kern, ein gezielt geladener iOS-Skill und eine manuelle Abnahme. Ein dauerhaft stark belastetes Team mit eigener Geräteflotte, festen Signierungsprozessen und stabiler CI sollte dagegen prüfen, ob eine selbst verwaltete Umgebung langfristig mehr Kontrolle bietet.

Die aktuelle Lösung hat jedoch klare Grenzen, wenn der Entwickler-Mac unregelmäßig verfügbar ist, Simulator- und Xcode-Zustände zwischen Aufträgen schwanken oder mehrere Personen auf dieselbe Abnahme warten. Dazu kommen Berechtigungsrisiken bei gemeinsam genutzten Schlüsselbunden und die Schwierigkeit, ein Ergebnis außerhalb der vorgesehenen Mac-Umgebung zu reproduzieren.

Wenn Sie zunächst nur einen risikoarmen Auftrag prüfen oder zeitweise eine verlässlich erreichbare Xcode-Abnahme benötigen, kann die Anmietung eines Mac-Arbeitsbereichs von SSHMac die praktischere Ergänzung sein. Sie sollten trotzdem dieselben Übergaberegeln, Protokolle und Berechtigungsgrenzen anwenden: Ein gemieteter Mac ersetzt weder AGENTS.md noch Skills, sondern liefert die Ausführungsumgebung, in der sich deren Anweisungen tatsächlich überprüfen lassen.