Ich habe dreimal Paprikapulver gekauft, weil ich es an drei verschiedenen Stellen aufbewahrt habe.
In der Wohnung hing schon ein Gewürzregal über dem Herd. Als es voll war, habe ich eine Schublade eingeräumt. Dann kam noch ein Regalbrett in der Vorratskammer dazu. Jede dieser Lösungen ergab Sinn, als ich sie mir ausdachte. Zusammen machten sie es erstaunlich schwer, das Paprikapulver zu finden.
Aufgefallen ist mir das Problem, als ein Freund bei mir gekocht hat. Ich stand den ganzen Abend hinter ihm: Die gute Pfanne steht unter der Spüle, das Salz da ist grob, der Ofen wird heißer als eingestellt. Er kocht besser als ich. Er brauchte eben nur eine Wegbeschreibung durch meine Küche.
Im August wurde mir klar, dass ich mit unseren Repositorys genau dasselbe gemacht hatte.
Die doppelten Regeln
OwlMeans-Projekte enthalten mehr als Quellcode. Sie bringen Anweisungen für den Coding-Agenten mit: wo was liegt, welche Befehle er ausführen soll und was eine Änderung überstehen muss.
Wir unterstützten Claude Code und GitHub Copilot. Eine Regel für den einen wurde zum Skill unter .claude/skills/, der andere bekam eine Kopie unter .github/instructions/. Projektübersichten, Shell-Skripte und das Gedächtnis legten sich ebenfalls Zwillinge zu.
Ein einziger Commit änderte zwölf Skill-Dateien und elf gespiegelte Fassungen. Zu jeder Korrektur gehörte eine kleine Frage: Hatte ich die andere Kopie auch korrigiert?
In OwlMeans Common hat das Aufräumen 213 doppelte Anweisungsdateien entfernt. Diese Zahl beschreibt die Änderung an unserem Repository. Wie viel schneller ein Agent dadurch geworden ist, sagt sie nicht.
An ihre Stelle traten ein einziger maßgeblicher Ordner .agents/ und eine AGENTS.md im Wurzelverzeichnis. Skills, Regeln, Skripte und das gemeinsame Gedächtnis bekamen jeweils ihren Platz. Agentenspezifische Dateien wurden zu Brücken, die auf diese Quelle verweisen.
Das gemeinsame Format
AGENTS.md gibt einem Agenten Projektanweisungen in einer gewöhnlichen Markdown-Datei. Die Agent-Skills-Spezifikation legt die Struktur eines Skill-Ordners und seiner SKILL.md fest.
Beide lösen unterschiedliche Probleme. Die Datei im Wurzelverzeichnis sagt dem Agenten, wie er in diesem Repository arbeiten soll. Ein Skill enthält ein Vorgehen, das er für eine bestimmte Aufgabe laden kann.
Das übergeordnete Verzeichnis schreibt die Skill-Spezifikation nicht vor. .agents/skills/ war unsere eigene Konvention, und wir haben sie für die Werkzeuge gewählt, die wir damals benutzten. Ich sollte nicht so tun, als hätte jeder Agent versprochen, dieses Verzeichnis zu finden.
Wichtig wird dieser Unterschied, sobald du ein weiteres Werkzeug hinzunimmst. Gemeinsamer Text hilft nur, wenn das Werkzeug ihn auch tatsächlich lädt.
Die Brücke zu Claude
In unserem Setup vom August gab es weiterhin eine kleine CLAUDE.md, deren erste Anweisung @AGENTS.md lautete. Ein Skript erzeugte für jeden Skill einen eigenen Symlink in .claude/skills/.
So fand Claude Code seine gewohnten Einstiegspunkte vor, und wir mussten trotzdem keinen weiteren Satz Anweisungen pflegen. Der Session-Hook hat die Links jeweils erneuert.
Auf die Links pro Skill sind wir gekommen, indem wir das Setup getestet haben. Das ganze Skill-Verzeichnis zu verlinken, hatte in unserer Konfiguration nicht funktioniert. Das ist eine Beobachtung zu genau diesem Setup und keine dauerhafte Regel für jede künftige Version von Claude Code.
Am 15. Oktober 2026 habe ich noch einmal nachgesehen: Die Anfrage nach nativer Unterstützung für AGENTS.md war weiterhin offen. Wenn du heute installierst, prüfe die aktuelle Dokumentation zum Gedächtnis von Claude Code und teste, was Claude Code tatsächlich einliest. Unsere Brücke sagt weiterhin ausdrücklich, welche Quelle sie importiert.
Anweisungen, die sich lohnen
Mit dem Umzug der Dateien waren die Dopplungen weg. Nützlich wurde ihr Inhalt dadurch noch nicht.
Ein allgemeiner Skill über guten Code verrät einem Agenten wenig über unsere Entrypoints oder unsere Projekt-Slots. Nützliche Anweisungen erklären diese Codebasis: welchem Paket eine Ressource gehört, welche Grenze eine Änderung einhalten muss und welche Prüfung den Fehler findet.
Die Pakete von OwlMeans Common bringen neben ihrem Code auch Anweisungen mit. Ein generiertes Projekt kann diese Anweisungen über @owlmeans/agent-skills installieren. Die Metadaten der Pakete liefern die Anweisungen, das Repository liefert den lokalen Kontext.
Pflegen muss beides trotzdem jemand.
Bei uns gilt: Nach größeren geplanten Arbeiten sehen wir uns die betroffenen Skills noch einmal an. Hat sich ein Befehl, ein Pfad oder ein Verhalten geändert, schreiben wir die Anweisung neu, die es beschreibt. Ein Skill gibt die aktuelle Regel wieder. Eine datierte Notiz, dass die alte Regel nicht mehr funktioniert, überlässt dem nächsten Agenten die Entscheidung, welcher Absatz gilt.
Das hat seinen Preis. Manche Aufgaben enden mit Arbeit an der Dokumentation, wenn der Code die Prüfungen schon besteht. Ich zahle diesen Preis lieber, solange ich noch weiß, warum sich die Implementierung geändert hat.
Gedächtnis nach Subsystemen
Beim Gedächtnis gab es eine andere Art von Dopplung. Wir führten dort Protokoll über unsere Aufgaben.
Eine Datei, die nach einer Untersuchung benannt war, sagte mir, was in jener Woche passiert war. Um herauszufinden, was beim Routing nun eigentlich galt, musste ich mehrere Untersuchungen lesen und klären, welche davon die anderen ablöste.
Das Gedächtnis haben wir neu gegliedert, entlang der Struktur des Projekts: Routing, Übersetzungen, Deployment, externe Dienste. Ein Index ordnet diese Knoten den Pfaden zu, die sie abdecken. Der Agent liest zuerst diese Übersicht und öffnet dann die passenden Knoten.
Wer ins Gedächtnis schreibt, aktualisiert den passenden Fakt direkt an seiner Stelle, statt einen weiteren datierten Bericht unter einen veralteten zu hängen. Laufende Arbeit darf ein Datum tragen. Gesicherte Anweisungen sollten sich aber lesen lassen, ohne dass man die Sitzung rekonstruieren muss.
Im Repository der Plattform wurden aus zwanzig chronologischen Dateien elf strukturelle Knoten. Das waren unsere Zahlen bei der Umstellung. Der eigentliche Gewinn war, dass ich wusste, wo ich nachsehen muss.
Auch ein Gedächtnis muss korrigiert werden. Seine Struktur kann nicht verhindern, dass eine falsche Annahme darin landet. Und ein kurzer Index garantiert nicht, dass der Agent die richtige Seite lädt. Aber wir haben damit einen Ort, an dem wir die Annahme reparieren können, sobald wir sie finden.
Die zwei Wochen
Die Umstellung hat zwei Wochen gedauert. Einen Teil davon habe ich mit Verzeichniskonventionen verbracht, den anderen mit kleinen Kompatibilitätsproblemen, die erst auftauchen, wenn du einen weiteren Agenten laufen lässt.
Generierte OwlMeans-Projekte bringen Anweisungen für Agenten mit. Bei unseren Services passen wir außerdem Skills und Metadaten an das ausgelieferte Projekt an. Diese Anweisungen nützlich zu halten, bleibt Aufgabe derjenigen, die das Repository pflegen.
Mein Freund muss immer noch wissen, dass der Ofen heißer wird als eingestellt. Immerhin habe ich jetzt einen Ort, an dem ich das aufschreiben kann.
Erstmals veröffentlicht am 13. August 2026. Am 15. Oktober 2026 überarbeitet: Die gemeinsamen Formate sind jetzt klar von unserer Verzeichniskonvention getrennt, und die Beobachtungen zur Kompatibilität der Werkzeuge tragen ein Datum.