Skill verhält sich nur in einem Repository unterschiedlich → projektweit speichern.
Skill wird über mehrere unabhängige Projekte gebraucht → auf Benutzerebene ablegen.
Skill soll für ein Team reproduzierbar und kontrolliert bleiben → projektweit plus schreibgeschütztes, versioniertes Team-Verzeichnis einsetzen.

Diese Regel gilt besonders dann, wenn Ihr Skill nicht nur Text liefert, sondern Build-Schritte, Testregeln, Shell-Kommandos oder Zugriffe auf interne Werkzeuge beschreibt. Ein globaler, beschreibbarer Skill für Projekte mit unterschiedlichen Vertrauensgrenzen ist langfristig die schlechteste Standardlösung.

Diese Entscheidungshilfe richtet sich an:

• Einzelentwickler mit projektspezifischen Coding- und Testvorgaben,
• intensive Mehrprojekt-Nutzer, die einzelne Skills wiederverwenden möchten,
• Plattformingenieure, die Skills auf mehreren Macs oder in entfernten Ausführungsumgebungen verteilen müssen.

Die offizielle Konfigurationsreferenz beschreibt lokale Skill Provider für Projektwurzel, Benutzerwurzel, gemeinsam genutzte Agent-Verzeichnisse und benutzerdefinierte Pfade. Die konkrete Scan-Reihenfolge und Darstellung sollten Sie deshalb immer gegen die Version prüfen, die Sie tatsächlich ausführen. Offizielle Konfigurationsreferenz und Skill-Provider-Implementierung sind dafür die maßgeblichen Ausgangspunkte. (github.com)

Ein Skill ist kein gewöhnliches Markdown-Dokument. Eine Datei wie SKILL.md kann festlegen, wann ein Agent eine Fähigkeit auswählt, welche Dateien er liest und welche Werkzeuge er verwendet. Liegen zusätzlich Skripte oder Referenzdateien daneben, entsteht ein kleines Paket mit eigenem Verhaltensprofil.

Der Speicherort entscheidet deshalb über mindestens fünf Eigenschaften.

Versionsbindung

Ein projektspezifischer Skill gehört normalerweise zur gleichen Versionsgeschichte wie der Code, den er beschreibt. Ändert sich der Build-Prozess, muss die Anleitung gleichzeitig angepasst, geprüft und zurückgerollt werden können.

Ein globaler Skill hat diese Bindung nicht. Er kann heute zu Projekt A passen und morgen in Projekt B eine veraltete Annahme aktivieren. Das Problem zeigt sich oft nicht beim Laden, sondern erst bei einem falschen Testkommando oder einer unpassenden Dateistruktur.

Änderungsverantwortung

Im Projektverzeichnis ist meist klar, wer einen Pull Request prüfen muss. Im Benutzerverzeichnis ist die Verantwortung diffuser. Eine manuelle Änderung auf einem Mac kann später das Verhalten mehrerer Projekte beeinflussen, ohne dass im Repository eine nachvollziehbare Änderung auftaucht.

Für Teams ist das besonders kritisch. Zwei Entwickler können denselben Skill-Namen verwenden, aber unterschiedliche Inhalte besitzen. Der Agent sieht dann scheinbar dieselbe Fähigkeit, arbeitet jedoch nach verschiedenen Regeln.

Vertrauensgrenze

Ein Skill darf keine Zugangsdaten enthalten. API-Schlüssel, SSH-Schlüssel, lokale Pfade mit personenbezogenen Daten und interne Hostnamen gehören nicht in die Datei oder in zugehörige Referenzen. Das Repository sollte nur Anweisungen und reproduzierbare Konfiguration enthalten. Geheimnisse müssen über die dafür vorgesehene Umgebungs- oder Secret-Verwaltung eingebunden werden.

Ein globaler Pfad vergrößert die Reichweite eines Fehlers. Ein kompromittiertes oder versehentlich geändertes Skill-Paket kann auf jedes Projekt wirken, das denselben Benutzerbereich verwendet.

Erkennung und Sitzungsgrenze

Dass eine neue Datei auf der Festplatte liegt, bedeutet nicht automatisch, dass die laufende Sitzung sie bereits kennt. Je nach Version können Katalog, Dateiwatcher und Tool-Auflistung unterschiedlich reagieren. Wenn ein neuer Skill nicht auftaucht, sollten Sie daher nicht sofort den Inhalt umschreiben.

Prüfen Sie zuerst:

1. Liegt das Skill-Verzeichnis unter einem tatsächlich konfigurierten Provider-Pfad?
2. Enthält es eine korrekt benannte SKILL.md?
3. Ist der Skillname eindeutig?
4. Wurde der Katalog nach der Änderung neu eingelesen?
5. Funktioniert die Erkennung auch nach einem Neustart?

Die offizielle Skill-Struktur und die erwartete Rolle von SKILL.md sollten Sie anhand der Skill-Dokumentation im Quellbestand und des Werkzeugmoduls für Skill-Laden kontrollieren. (github.com)

Einzelentwickler: Skill mit dem Repository ausliefern

Wenn der Skill den Build, die Tests, die Dateistruktur oder die Release-Regeln eines einzelnen Projekts erklärt, gehört er in das Projekt. Praktisch bedeutet das ein projektbezogenes Skill-Verzeichnis unterhalb der Repository-Wurzel, sofern Ihr Provider dieses Verzeichnis aktiviert.

Das bringt drei Vorteile:

• Die Anleitung reist mit dem Code.
• Änderungen können wie Code geprüft werden.
• Ein Checkout auf einem zweiten Mac erhält dieselbe Arbeitsgrundlage.

Der wichtigste Nachteil ist zusätzlicher Pflegeaufwand. Wenn zehn Projekte dieselbe allgemeine Git-Regel benötigen, entstehen zehn Kopien. Diese Kopien dürfen nicht stillschweigend auseinanderlaufen. Verwenden Sie deshalb projektweit nur Inhalte, die wirklich an dieses Repository gekoppelt sind.

Ein Beispiel: Ihr Projekt verlangt eine bestimmte Reihenfolge aus Formatierung, Unit-Tests und Integrationsprüfung. Der Skill nennt konkrete Pfade und Skriptnamen. Diese Anleitung ist projektweit sinnvoll. Eine allgemeine Erklärung, wie ein sauberer Commit aufgebaut ist, muss dagegen nicht in jedem Repository separat gepflegt werden.

Mehrprojekt-Nutzer: nur echte Fähigkeiten global speichern

Ein persönlicher globaler Skill eignet sich für Abläufe, die keine Projektannahmen enthalten. Dazu zählen etwa eine allgemeine Code-Review-Struktur, ein neutrales Format für Fehlermeldungen oder ein persönliches Vorgehen zur Analyse von Testfehlern.

Global sollten Sie nur speichern, was alle Projekte vertragen. Prüfen Sie vor der Ablage:

• Verweist der Skill auf eine feste Repository-Struktur?
• Ruft er ein internes Skript auf?
• Erwartet er bestimmte Abhängigkeiten?
• Enthält er Regeln, die nur für eine Organisation gelten?
• Könnte er bei einer harmlosen Nutzeranfrage unerwartet ausgelöst werden?

Wenn Sie eine dieser Fragen mit „Ja“ beantworten, ist der globale Pfad wahrscheinlich zu weit gefasst.

Der globale Bereich ist bequem zu aktualisieren. Genau diese Bequemlichkeit erzeugt aber Versionsdrift. Eine Änderung wird sofort in mehreren Projekten wirksam. Ein gut gemeinter Fix für ein React-Projekt kann bei einem Python-Projekt falsche Prüfungen oder unnötige Rückfragen auslösen.

Kleine Teams: projektweit plus schreibgeschützter gemeinsamer Ursprung

Für ein kleines Team ist eine zweistufige Lösung meist belastbarer als ein gemeinsamer, beschreibbarer Ordner.

Der gemeinsame Skill liegt in einem versionierten Team-Repository oder einem kontrollierten Artefaktverzeichnis. Das Projekt übernimmt daraus eine ausdrücklich freigegebene Version. Je nach Tool-Unterstützung kann dies durch Kopieren, Synchronisieren oder einen Verweis erfolgen. Die Arbeitskopie im Projekt sollte für den täglichen Agent-Lauf schreibgeschützt sein.

Damit trennen Sie zwei Verantwortlichkeiten:

• Das Plattform- oder Maintainer-Team pflegt den gemeinsamen Skill.
• Das Projekt entscheidet, wann es auf eine neue freigegebene Version wechselt.

Jede Änderung braucht eine Versionskennung, eine kurze Änderungsbeschreibung und einen Rückfallpunkt. Wenn ein neues Testverfahren Probleme verursacht, muss das Projekt auf die vorherige Fassung zurückkehren können, ohne auf einem einzelnen Entwickler-Mac nach einer Sicherung suchen zu müssen.

Ein typischer Teamfall

Ein Team betreibt mehrere Services mit einer gemeinsamen Sicherheitsprüfung. Die Prüfung selbst ist zentral. Die Liste der zu prüfenden Dateien unterscheidet sich jedoch je Repository.

Die gemeinsame Version enthält nur den Prüfablauf. Das Projekt-Skill ergänzt die lokalen Pfade und Ausnahmefälle. So bleibt der gemeinsame Teil konsistent, während das Repository seine eigenen Annahmen kontrolliert.

Diese Trennung verhindert auch, dass ein Projekt versehentlich eine organisationsweite Regel überschreibt. Ein schreibbarer globaler Ordner wäre hier zwar schnell eingerichtet, aber schwer auditierbar.

Plattformteams: pro Ausführungspool eine feste Skill-Liste

In einer CI/CD- oder Remote-Mac-Umgebung sollten Sie nicht davon ausgehen, dass der persönliche Benutzerordner eines Administrators verfügbar ist. Ein neuer Ausführungsknoten kann mit einem anderen Benutzer, einem frischen Home-Verzeichnis oder einem neu erstellten Dateisystem starten.

Die Skills müssen deshalb Teil des Images, der Initialisierung oder des offiziell übergebenen Arbeitsverzeichnisses sein. Entscheidend ist nicht nur, dass die Dateien kopiert werden. Sie müssen nach dem Start auch entdeckt und bei Bedarf geladen werden.

Für jeden Ausführungspool sollten Sie eine feste Skill-Liste dokumentieren:

• Skillname und freigegebene Version,
• Quelle und Prüfsumme,
• Zielpfad,
• Besitzer und Schreibrechte,
• erwartetes Verhalten nach Neustart,
• Rückfallversion,
• zuständiges Team.

Ein Pool für Produktionsänderungen darf nicht automatisch dieselben schreibbaren Skills verwenden wie ein Experimentierpool. Die Inhalte können ähnlich sein. Die Berechtigungen und Freigaben müssen es nicht sein.

Wenn ein neuer Skill nicht sichtbar ist, liegt die Ursache häufig nicht in der Beschreibung, sondern in der Umgebung.

Erste Prüfung: Pfad und Variable

Wenn Sie mit DSH_HOME arbeiten, prüfen Sie zunächst, ob die Variable im Prozess des Harness tatsächlich gesetzt ist. Ein Eintrag in einer interaktiven Shell genügt nicht, wenn der Agent über einen Dienst, einen Launch-Mechanismus oder eine CI-Initialisierung gestartet wird.

Prüfen Sie außerdem, ob der erwartete Pfad wirklich existiert und lesbar ist. Ein Verzeichnis kann im Terminal sichtbar sein, aber für den Dienstbenutzer fehlen.

Zweite Prüfung: Struktur

Ein Skill sollte als eigenes Verzeichnis vorliegen. Die Datei SKILL.md muss dort liegen, wo der Provider sie erwartet. Achten Sie auf Groß- und Kleinschreibung, besonders auf Dateisystemen oder Synchronisationsdiensten mit unterschiedlichem Verhalten.

Begleitdateien sollten über relative Pfade erreichbar sein. Absolute Pfade aus Ihrem persönlichen Mac gehören nicht in einen Team-Skill.

Dritte Prüfung: Katalog und Dateiwatcher

Falls die offizielle Konfiguration einen Dateiwatcher unterstützt, muss dieser auf den tatsächlich verwendeten Root zeigen. Ein Watcher kann außerdem nur neue Änderungen erkennen, wenn der Prozess läuft und der Pfad nicht durch einen Container- oder Mount-Wechsel ersetzt wurde.

Für eine belastbare Diagnose starten Sie eine neue Sitzung. Wenn der Skill dann auftaucht, war vermutlich der alte Katalog bereits geladen. Wenn er weiterhin fehlt, vergleichen Sie Provider-Konfiguration, Benutzerrechte und Verzeichnisstruktur.

Ein Symlink kann die Teamverwaltung vereinfachen, aber auch die Vertrauensgrenze verschleiern. Der sichtbare Pfad gehört dann nicht unbedingt zum erwarteten Besitzer oder Dateisystem. Bei einem Remote-Mac kann der Link ins Leere zeigen, auf ein nicht gemountetes Laufwerk verweisen oder auf eine persönliche Arbeitskopie zeigen.

Für sicherheitsrelevante Skills sollten Sie daher strenger prüfen:

• Besitzt der erwartete Benutzer den Link und das Ziel?
• Ist das Ziel innerhalb der freigegebenen Umgebung?
• Bleibt der Link nach einem Neustart gültig?
• Kann ein Projekt den Zielinhalt verändern?
• Werden Links in der Übergabe bewusst verfolgt oder absichtlich blockiert?

Ein Skill muss wie eine verhaltenssteuernde Asset-Datei behandelt werden. Lesen Sie den Inhalt. Prüfen Sie Skripte. Begrenzen Sie Schreibrechte. Übernehmen Sie keine unbekannten Skills direkt in einen globalen, automatisch geladenen Bereich.

Für die Sicherheitsbewertung können Sie zusätzlich die offizielle Tool- und Plugin-Struktur sowie die Beispielkonfiguration heranziehen. (github.com)

Verwenden Sie diese Bedingungen vor jeder Ablage:

• Wenn der Skill konkrete Repository-Pfade, Build-Befehle oder Testvorgaben enthält, dann wählen Sie den projektweiten Pfad.
• Wenn der Skill in mehreren Projekten funktioniert und keine internen Pfade voraussetzt, dann ist der Benutzerbereich geeignet.
• Wenn mehrere Personen dieselbe Fähigkeit benötigen, dann pflegen Sie einen versionierten gemeinsamen Ursprung.
• Wenn das Team Änderungen kontrollieren und zurückrollen muss, dann übernehmen Projekte eine freigegebene Version statt direkt aus einem schreibbaren Shared-Verzeichnis zu lesen.
• Wenn ein Remote-Ausführungspool reproduzierbar starten muss, dann liefern Sie den Skill über Image, Initialisierung oder ein versioniertes Arbeitsartefakt aus.
• Wenn Projekte unterschiedliche Geheimnisse, Dateirechte oder Compliance-Regeln haben, dann vermeiden Sie einen gemeinsam beschreibbaren globalen Pfad.
• Wenn ein Symlink über eine Vertrauensgrenze hinweg zeigt, dann behandeln Sie ihn wie eine externe Abhängigkeit und prüfen Sie Besitzer, Ziel und Neustartverhalten.

Damit lautet die belastbare Standardentscheidung: Projekt-Skills projektweit, persönliche Standards global, Team-Skills versioniert und möglichst schreibgeschützt.

Die Tabelle ist keine Rangliste. Ein projektweiter Skill ist nicht automatisch besser. Er ist besser, wenn seine Gültigkeit an genau dieses Repository gebunden ist.

Führen Sie die Prüfung nicht nur auf Ihrem Entwicklungs-Mac aus. Wiederholen Sie sie auf einer frischen oder entfernten Umgebung.

1. Legen Sie einen eindeutig benannten Test-Skill in den vorgesehenen Root.
2. Starten Sie eine neue DeepSeek Harness-Sitzung.
3. Prüfen Sie, ob der Skill im Katalog erscheint.
4. Fordern Sie eine Aufgabe an, die den Skill eindeutig auslösen müsste.
5. Kontrollieren Sie, ob nur die erwarteten Dateien und Werkzeuge verwendet werden.
6. Ändern Sie den Skill kontrolliert und prüfen Sie das Verhalten des Watchers.
7. Starten Sie den Prozess oder die Umgebung neu.
8. Wiederholen Sie die Aufgabe und dokumentieren Sie das Ergebnis.
9. Testen Sie ein zweites Repository, um unerwünschte globale Auswirkungen auszuschließen.
10. Entfernen Sie die Testdatei und prüfen Sie, ob sie aus dem Katalog verschwindet oder erst nach einem Neustart nicht mehr auftaucht.

Diese letzte Prüfung beantwortet zugleich die häufige Frage, ob mehrere Projekte denselben Skill verwenden können: Ja, technisch kann ein gemeinsamer Skill für mehrere Projekte funktionieren. Organisatorisch ist das aber nur sinnvoll, wenn Inhalt, Schreibrechte, Version und Vertrauensgrenze tatsächlich gleich sind.

Wenn Sie Skills auf einem Cloud-Mac oder in einem entfernten Ausführungspool einsetzen, behandeln Sie das Skill-Verzeichnis als Teil der Umgebungssignatur. Zur Übergabe gehören nicht nur Code und API-Zugang, sondern auch die freigegebene Skill-Version, der Zielpfad, die Berechtigungen und das Ergebnis des Neustarttests.

Für eine temporäre Testumgebung kann eine projektbezogene Kopie genügen. Für wiederkehrende Teamaufgaben ist ein versioniertes Übergabepaket besser. Es verhindert, dass ein Benutzerordner zufällig den Inhalt bestimmt.

Bei der Auswahl einer entfernten Mac-Umgebung sollten Sie deshalb nicht nur Rechenleistung oder Mietkosten vergleichen. Prüfen Sie, ob die Umgebung Ihre Skills reproduzierbar übernehmen kann und ob ein Neustart denselben Katalog erzeugt. Einen passenden Ausgangspunkt für die Mac-Auswahl für entfernte Entwicklungsumgebungen finden Sie bei KVMNODE. Für verfügbare Regionen und die aktuelle Mac-Mietübersicht sollten Sie die jeweilige Betriebsart separat bewerten.

KVMNODE ist für diese Entscheidung besonders dann interessant, wenn Sie kurzfristig einen reproduzierbaren Mac-Testknoten benötigen. Für dauerhaft hohe Last, spezielle physische Schnittstellen oder eine langfristig unveränderte Eigenumgebung kann der Kauf eines eigenen Macs sinnvoller sein. Eine Mietumgebung ersetzt keine Governance. Sie hilft Ihnen nur, die Übergabe und Wiederherstellung sauber zu testen, ohne sofort eigene Hardware dauerhaft zu binden.

Wenn Ihr aktueller Ansatz Skills manuell in mehreren Home-Verzeichnissen verteilt, entstehen schnell drei konkrete Nachteile: unterschiedliche Versionen, unklare Änderungsverantwortung und fehlende Sicherheit nach einem Neustart. Ein projektweit gespeicherter Skill mit versioniertem gemeinsamen Ursprung beseitigt diese Fehlerquellen deutlich besser. Für die Abnahme auf einem entfernten Mac sollten Sie daher nicht nur prüfen, ob der Agent startet, sondern ob Verzeichnis, Version, Rechte und Skill-Erkennung gemeinsam reproduzierbar sind.