1. Architektur und Pflichtabschnitte der SKILL.md-Datei

Die Datei SKILL.md ist ein ingenieurtechnisches Werkzeug, das ein universelles Sprachmodell in einen spezialisierten Ingenieur für die Ausführung eines klar definierten Aufgabentyps verwandelt. Sie dupliziert keine globalen Projektinvarianten, sondern fügt ihnen schmales, hochspezifisches prozedurales Wissen hinzu.

Bevor du eine Skill für dein eigenes Repository erstellst, musst du zwingend die allgemeine Konfigurationsdatei der Projektregeln (AGENTS.md oder CLAUDE.md) studieren. Diese Systemdokumente sind die absolute Quelle der Wahrheit für kritische Sicherheitsregeln und Build-Befehle. Die Aufgabe der Skill selbst besteht darin, den Agenten in Struktur und Abfolge der Schritte zu unterweisen, wobei sie auf die Systemregeln verweist, anstatt sie zu kopieren.

mermaid

flowchart TD subgraph Structure ["Чотири обов'язкові компоненти якісного SKILL.md"] F["1. Description у Frontmatter (Формулюється строго як УМОВА, а не тема)"] T["2. When to Trigger (Точні контекстні критерії та ключові слова)"] P["3. Procedure (Нумеровані кроки з реальними командами й шляхами)"] Pit["4. Pitfalls & Anti-Patterns (Дія + Наслідок + Точне виправлення)"] end F --> T --> P --> Pit

Detaillierte Analyse der Pflichtabschnitte

Description im Frontmatter: Der einzige Textblock, den der Agent vor der Entscheidung über das Laden der Skill liest. Er muss als prädikative Aktivierungsbedingung formuliert werden („Verwende, wenn...“), nicht als abstraktes Thema.
When to trigger (Wann aktivieren): Eine detaillierte Liste direkter Anfragen, Log-Fehler oder Git-Operationen, bei denen die Skill zwingend ausgelöst werden muss.
Procedure (Reglementiertes Verfahren): Ein nummerierter Algorithmus mit exakten Namen lokaler Befehle und validierten Pfaden zu Dateien.
Pitfalls (Fallstricke): Ein Katalog dokumentierter früherer Ausfälle. Jeder Eintrag folgt der Formel: Konkrete fehlerhafte Handlung → Exakter technischer Fehler → Rezept zur Behebung.

Hinweis

Wenn die Skill mit einem Release- oder Deploy-Prozess endet, dupliziere nicht die Pipeline innerhalb der Skill. Beende den Algorithmus stattdessen mit der Anweisung: „Führe die Skill ship-pipeline aus“.

2. Speicherstruktur: Synchronisation zwischen Codex und Claude Code

In modernen Workflows nutzen Entwickler häufig mehrere Clients gleichzeitig (z. B. OpenAI Codex im Terminal oder IDE sowie Claude Code). Beide Runtimes unterstützen die offene Skill-Spezifikation, erwarten diese jedoch in unterschiedlichen Projektverzeichnissen.

Speicherpfade für Skill-Dateien in Codex- und Claude-Code-Runtimes Збільшити

Speicherpfade für Skill-Dateien in Codex- und Claude-Code-Runtimes

Pfad-Matrix für Runtimes

Runtime / Agent	Ziel-Pfad der SKILL.md-Datei	Erkennungsmerkmale
OpenAI Codex	`.agents/skills/<name>/SKILL.md`	Wird vom Codex-Agenten beim Scannen lokaler Tools gelesen
Anthropic Claude Code	`.claude/skills/<name>/SKILL.md`	Wird von Claude Code bei der Initialisierung der Sitzungsumgebung gelesen

Wichtig

Anforderung zur dualen Synchronisation: Wenn eine Skill nur in .claude/skills/ hinzugefügt wurde, ist sie für Codex-Agenten vollständig unsichtbar – und umgekehrt. Erstelle und pflege Skills immer in beiden Verzeichnissen oder konfiguriere symbolische Links (Symlinks).

3. Reifekriterien und Validierung des Draft-Skills

Bevor du eine Skill in das Team-Repository übergibst, bewerte sie anhand einer standardisierten ingenieurtechnischen Qualitätsskala:

Falsifizierbarkeit des Triggers: Du kannst mindestens 2 angrenzende Anfragen im selben Fachbereich nennen, bei denen die Skill NICHT ausgelöst werden darf.
Befehl-Audit: Jeder ausführbare Befehl im Verfahren existiert im Abschnitt Local Commands der Systemdatei AGENTS.md.
Faktische Fallstricke: Jeder Punkt im Abschnitt Pitfalls beschreibt einen realen Vorfall aus der Praxis, keine allgemeine Warnung wie „sei vorsichtig“.
Kontaktkompaktheit: Das Lesen des Skill-Texts dauert maximal 2–3 Minuten (bis zu 500 Zeilen).
Null-Duplizierung: Kein Absatz kopiert allgemeine Regeln aus AGENTS.md.

mermaid

flowchart LR Draft["Чорновий Skill (Розмитий опис, копії правил, абстрактні кроки)"] --> Review{"Валідація чернетки"} Review -->|Виявлено недоліки| Fix["Виправлення формулювань і команд"] Fix --> Review Review -->|Всі критерії виконано| Prod["Production-Ready Skill"]

4. Kompositionsmuster: Dispatcher, Referenzen und Ketten

Reale Workflows sind selten auf eine einzelne Datei isoliert. Der Versuch, alles in einer monolithischen SKILL.md zu beschreiben, führt zur Kontextaufblähung und zum Nachlassen der Modellattention. Nutze drei bewährte architektonische Muster:

Muster 1: Entry Router (Skill-Dispatcher)

Eine allgemeine Skill fungiert als Routing-Karte. Sie analysiert die Nutzerabsicht und delegiert die Aufgabe an spezialisierte Sub-Skills:

text

Запит: "Оптимізуй продуктивність запитів до бази" └── db-router (Entry Router) ├── Спрямовує на: neon-migrations (якщо потрібні зміни структури) └── Спрямовує на: drizzle-index-optimizer (якщо потрібні індекси)

Muster 2: Reference-Dateien

Die Hauptdatei SKILL.md enthält nur den High-Level-Algorithmus, während komplexe Details, Tabellen und Grammatiken in das Verzeichnis references/ ausgelagert werden:

text

.claude/skills/fleet-coordinator/ ├── SKILL.md # Короткий пайплайн оркестрації └── references/ ├── agent-roles.md # Опис спеціалізацій та матриці ролей └── file-ownership.md # Правила запобігання конфліктам при записі

Muster 3: Skill Chain (Skill-Kette)

Skills verweisen über das Feld relatedPaths oder eine textuelle Direktive aufeinander als nächsten logischen Schritt:

markdown

> Після успішного проходження валідації схеми обов'язково запусти навичку drizzle-migration-runner.

5. Refactoring-Strategien: Wann teilen, wann zusammenführen?

Die Wahl zwischen Aufteilung und Zusammenlegung von Skills bestimmt die Robustheit deines Automatisierungssystems.

Tipp

In 90 % der Fälle ist die Aufteilung die richtige Entscheidung. Der Versuch, eine „universelle Skill für das gesamte Backend“ zu erstellen, verwandelt sich unvermeidlich in einen ineffizienten Monolithen mit hohem Halluzinationsgrad.

6. Versionierungsvertrag und Build-Pipeline für Flaggschiff-Skills

In komplexen Codebasen werden Skills nach ihrer Verbreitungs- und Build-Methode in drei technologische Ebenen unterteilt:

Build- und Speicher-Matrix verschiedener Skill-Typen im System Збільшити

Build- und Speicher-Matrix verschiedener Skill-Typen im System

Skill-Typ	Wo der Quellcode editiert wird	Build-Pipeline	Zweck
Repository-Skill (privat)	`.agents/skills/<name>/SKILL.md` + `.claude/skills/<name>/SKILL.md`	Nicht erforderlich (direktes Lesen)	Interne Team-Regeln für das aktuelle Projekt
Öffentliches Flaggschiff (Multi-File)	`skills-source/<slug>/` + Metadaten im Generierungsskript	`node scripts/build-flagship-skills.mjs skills-source/`	Komplexe modulare Lösungen mit Reference-Dateien für den Marktplatz
Öffentliche Single-File-Skill	`baseSkills` in `lib/library/skills.ts`	Nicht erforderlich	Leichtgewichtige Basis-Skills für den Plattformkatalog

Warnung

Verbot manueller Bearbeitung generierter Dateien: Bearbeite niemals kompilierte Flaggschiff-Skill-Dateien manuell. Änderungen werden ausschließlich im Quellordner skills-source/<slug>/ vorgenommen, gefolgt von der Ausführung des Kompilierungsskripts.

7. Testmethodologie: Fünf obligatorische Qualitätsprüfungen

Das Schreiben einer Anleitung ist nur der Anfang. Damit die Skill zuverlässig in Produktion funktioniert, muss sie fünf Testphasen konsistent durchlaufen:

mermaid

flowchart TD T1["1. Trigger Probe (3 позитивні + 2 негативні запити)"] --> T2["2. Procedure Walk-Through (Наскрізний запуск на реальному репозиторії)"] T2 --> T3["3. Pitfall Audit (Перевірка формули: Дія + Збій + Фікс)"] T3 --> T4["4. Scope Test (Перевірка єдиної відповідальності одним реченням)"] T4 --> T5["5. Staleness Check (Звірка команд і шляхів з актуальним репозиторієм)"] T5 --> Ready["Схвалено до коміту"]

Details des Testprotokolls

Trigger Probe (Trigger-Prüfung): Formuliere 3 Anfragen, die die Skill aktivieren sollen, und 2 Anfragen, die abgewiesen werden müssen. Prüfe, ob die Beschreibung im Frontmatter diese Fälle klar voneinander abgrenzt.
Procedure Walk-Through (Live-Durchlauf): Gehe jeden Schritt manuell auf einer Live-Staging-Umgebung durch. Wenn dir für einen Schritt Eingabedaten fehlten, fehlt in der Skill eine wichtige Bedingung.
Pitfall Audit (Ausfall-Audit): Stelle sicher, dass jeder beschriebene Fallstrick tatsächlich in der Praxis aufgetreten ist und der vorgeschlagene Fix funktioniert.
Scope Test (Fokus-Test): Formuliere den Zweck der Skill in einem einfachen Satz. Wenn der Satz das Wort „und auch“ erfordert, sollte die Skill in zwei Teile gespalten werden.
Staleness Check (Veraltetheitskontrolle): Vergleiche jeden CLI-Befehl mit der aktuellen Repository-Konfiguration und den gültigen Abhängigkeitsversionen.

8. Anatomie der Anti-Patterns: Wie unterscheidet man eine funktionierende Skill von einem Entwurf?

Der Vergleich typischer Fehler ermöglicht einen schnellen Selbstaudit vor dem Speichern der Skill.

Merkmal	Entwurf (Draft)	Produktionsreife Skill (Ready)
Trigger-Formulierung	Beschreibt ein breites Thema: „Für die Arbeit mit Datenbanken“	Definiert eine exakte Bedingung: „Verwenden bei Erstellung von Drizzle-Migrationen“
Schrittbeschreibung	Vage Anweisungen: „Linter bei Bedarf ausführen“	Klare Befehle: „npm run lint:fix ausführen“
Gefahrenbeschreibung	Allgemeine Warnung: „Sei vorsichtig mit Dateien“	Konkreter Fehler: „git add auf nicht-existentem Pfad bricht Staging ab“
Regelquellen	Kopiert Text aus `AGENTS.md` in den Inhalt	Enthält direkten Verweis auf den Abschnitt in `AGENTS.md`
Synchronisation	Nur in `.claude/skills/` erstellt	Gleichzeitige Synchronisation in `.agents/` und `.claude/`

9. Vermeidung von Fallstricken: Keine Duplizierung von AGENTS.md

Die tückischste Falle bei der Skill-Entwicklung ist die Duplizierung globaler Projektinvarianten (z. B. Regeln gegen Gedankenstriche, Anforderungen an runde Ecken in CSS oder das Verbot direkter Pushes auf main).

text

Чому дублювання руйнує систему: 1. Інженер копіює правило з AGENTS.md у тіло SKILL.md. 2. Через місяць архітектурний комітет оновлює правило в AGENTS.md. 3. Усередині SKILL.md залишається застаріле формулювання. 4. Агент отримує два суперечливі системні сигнали і починає галюцинувати.

Sichere Indexierung von Änderungen in Git

Bei der Ausführung von Commit-Prozessen innerhalb von Skills führe immer eine Prüfung der Pfadexistenz vor dem Hinzufügen zum Staging durch:

bash

# Небезпечно (якщо файл відсутній, вся команда переривається з помилкою): git add src/generated/schema.ts src/types/db.ts # Безпечно (додаються лише реально існуючі файли): [ -e src/generated/schema.ts ] && git add src/generated/schema.ts [ -e src/types/db.ts ] && git add src/types/db.ts

10. Abschließende Checkliste für die Produktionsreife

Überprüfe vor dem finalen Commit der erstellten Skill in Git jeden Punkt:

Die Skill ist in beiden Verzeichnissen synchronisiert: .agents/skills/<name>/SKILL.md und .claude/skills/<name>/SKILL.md.
Das Feld description beginnt mit den Worten „Verwende, wenn...“ und definiert klare Aktivierungsgrenzen.
Alle 5 Phasen des Testprotokolls (Trigger, Procedure, Pitfall, Scope, Staleness) wurden erfolgreich bestanden.
Im Text fehlen Unschärfe-Marker („bei Bedarf“, „entsprechend“).
Alle Konsolenbefehle wurden im Live-Terminal des Projekts getestet.
Globale Invarianten sind als Verweise auf AGENTS.md ohne direkten Textkopie gestaltet.