# Codex Skills für Einsteiger: So automatisieren Sie Workflows mit KI-Agenten > Ein praktischer Leitfaden zur Erstellung und Nutzung von Skills in Codex: Anatomie der SKILL.md, explizite und automatische Aktivierung, Unterschiede zwischen Skills, Skripten und Tools, die Skills API sowie die Konfiguration von Sicherheitsgrenzen. ## 1. Was ist ein Codex Skill: Der Übergang von einmaligen Prompts zu wiederholbaren Workflows Bei der täglichen Entwicklung mit **Codex** wiederholen Ingenieure oft denselben Satz an Eingabeanweisungen: Welche Dateien sollen geprüft werden, nach welchen Kriterien soll das Audit erfolgen, welche Architekturrichtlinien sind einzuhalten und in welchem Format soll das Ergebnis zurückgegeben werden? Wenn diese Anforderungen in jeder Session erneut manuell eingegeben werden müssen, sinkt die Produktivität und es kommt zu zufälligen Fehlern. Ein **Codex Skill (Fähigkeit)** ist ein gespeicherter, wiederverwendbarer Workflow für einen bestimmten Aufgabentyp. Die Erstellung eines Skills ist kein feines Nachtraining (Fine-Tuning) des Modells: Die Gewichte der KI bleiben unverändert. Stattdessen wird dem Agenten ein klar definierter prozeduraler Protokollrahmen bereitgestellt, den er dynamisch in sein Kontextfenster lädt, genau dann, wenn eine entsprechende Aufgabe auftritt. ```mermaid flowchart LR subgraph AdHoc ["Традиційний підхід (Ручний промптинг)"] User1["Користувач"] -->|Щоразу вводить довгі правила| Prompt["Великий разовий промпт"] Prompt --> Agent1["Codex"] end subgraph Modular ["Підхід на основі Skills"] User2["Користувач"] -->|Короткий запит: $code-review| Agent2["Codex"] SkillsDir["Репозиторій Skills (SKILL.md)"] -->|Автоматичне підвантаження інструкцій| Agent2 Agent2 --> Output["Стандартизований результат"] end ``` > [!NOTE] > Im offiziellen OpenAI-Ökosystem werden Skills bereits als Standard für Automatisierung genutzt. Beispielsweise stellt OpenAI für die Migration einer Codebasis auf neue Modelle den fertigen Skill `openai-docs` bereit, der alle Nuancen des aktuellen SDK kennt, ohne dass die Dokumentation manuell hochgeladen werden muss. --- ## 2. Auswahlkriterien: Wann ein Skill nötig ist und wann ein normaler Prompt ausreicht Skills sind primär für Prozesse gedacht, die eine ausgeprägte Wiederholbarkeit, eine stabile Abfolge von Schritten oder strenge Anforderungen an das Ausgabeformat haben. | Kriterium | Normaler Prompt | Codex Skill | | :--- | :--- | :--- | | **Nutzungsfrequenz** | Einmalige, einzigartige Aufgabe | Regelmäßiger Workflow (täglich oder vor jedem Release) | | **Prozesskomplexität** | 1–2 einfache Schritte | Mehrstufige, reglementierte Pipeline mit Validierung | | **Zusätzliche Dateien** | Nicht erforderlich | Erfordert begleitende Skripte, Referenzen oder Checklisten | | **Formatanforderungen** | Freie Antwort | Strikte Berichtsstruktur (z. B. JSON oder feste Tabelle) | | **Rechte & Einschränkungen** | Aktuelle Session-Einstellungen | Klar definierte erlaubte und verbotene Aktionen | ### Typische Szenarien für die Erstellung eines Skills - **Pre-Release-Repository-Prüfung:** Ausführung von Lintern, Suche nach übrig gebliebenem Debugging-Code (`console.log`, `TODO`), Prüfung der Typ-Kompatibilität. - **Standardisiertes Code-Review:** Überprüfung der Einhaltung interner Architekturrichtlinien des Teams ohne eigenständige Änderungen. - **Generierung von Release Notes:** Extraktion der Liste gemergter PRs, deren Kategorisierung und Aktualisierung der `CHANGELOG.md`. - **Komponenten-Migration:** Schrittweises Refactoring veralteter Patterns anhand eines vorab genehmigten Templates. > [!TIP] > **Praktische Ingenieursregel:** Wenn Sie sich dabei erwischen, wie Sie Codex zum dritten Mal dieselbe Schrittfolge erklären („lies zuerst diese Datei, führe dann diesen Test aus, ändere nichts, gib das Ergebnis als Tabelle aus“) – dieser Workflow sollte jetzt in einen separaten Skill gepackt werden. --- ## 3. Aktivierungsmechanik: Expliziter Aufruf via `$name` vs. automatische Zuordnung Codex unterstützt zwei komplementäre Methoden zur Aktivierung von Skills innerhalb einer Session: den direkten, deterministischen Aufruf durch den Benutzer und die automatische semantische Erkennung. ### Expliziter Aufruf (Explicit Invocation) Der Benutzer gibt den Namen des gewünschten Skills direkt über das Dollar-Zeichen-Präfix `$` an: ```bash $code-review перевір останні зміни у гілці feature/auth ``` Diese Methode garantiert 100 % Vorhersagbarkeit: Codex aktiviert sofort den angegebenen Skill, nutzt dessen Anweisungen als Verhaltensgrundlage und wendet sie auf die Argumente Ihrer Anfrage an. ### Automatische Aktivierung (Semantic Auto-Match) Wenn das Präfix `$name` nicht angegeben wird, analysiert Codex die Benutzeranfrage und gleicht sie mit den Feldern `description` aller verbundenen Skills ab: ```mermaid flowchart TD Req["Запит: 'Підготуй релізні нотатки для v2.1.0'"] --> Router{"Аналіз семантичного збігу"} Router -->|Match: description release-notes| LoadSkill["Підвантаження .codex/skills/release-notes/SKILL.md"] Router -->|No Match| Standard["Звичайний діалог без підвантаження навичок"] LoadSkill --> Exec["Виконання регламентованого сценарію"] ``` ```text Вдалий опис (висока ймовірність точного спрацювання): description: Перевіряє змінені файли проєкту на регресії, помилки типізації та стиль перед релізом. Використовуйте під час аудиту PR. Невдалий опис (розмиті межі): description: Допомагає розробнику краще писати код. ``` --- ## 4. Anatomie eines Skills und Struktur der SKILL.md: Metadaten, Regeln und Ressourcen Ein minimaler Skill besteht nur aus einer einzigen Datei – `SKILL.md`. Ausgereiftere Skills können eingebettete Automatisierungsskripte, Referenzhandbücher und Templates enthalten. ```text project-review/ ├── SKILL.md # Головний файл (метадані + інструкції) ├── scripts/ └── check-deps.sh # Виконуваний скрипт для швидких перевірок ├── references/ └── styleguide.md # Довідник: внутрішній код-стайл команди └── templates/ └── report-template.md # Шаблон підсумкового звіту ``` ### Struktur der Datei `SKILL.md` Die Datei ist in zwei funktionale Teile untergliedert: einen technischen YAML-Frontmatter-Block am Anfang und Anweisungen im Markdown-Format. ```markdown --- name: project-review description: Проводить комплексний аудит коду перед релізом, перевіряє типи та формує звіт про помилки без внесення правок. --- Інструкції для аудиту: 1. Запустити "npm run typecheck" для виявлення помилок TypeScript. 2. Проаналізувати git diff відносно гілки main. 3. Згрупувати знайдені зауваження за категоріями: Critical, Warning, Suggestion. 4. Нічого не змінювати у вихідному коді автоматично. 5. Надати підсумковий звіт відповідно до templates/report-template.md. ``` > [!IMPORTANT] > **Prinzip der Knappheit:** Überladen Sie `SKILL.md` nicht mit langen philosophischen Erklärungen. Je kürzer und präziser der Text, desto weniger wertvollen Platz belegt er im Kontextfenster des Modells und desto strikter hält sich der Agent an das Reglement. --- ## 5. Speicherbereiche: Projekt-Skills vs. persönliche globale Skills Codex unterscheidet Skills nach zwei Sichtbarkeitsbereichen je nach ihrem Zweck: ```mermaid flowchart TD subgraph GlobalScope ["Глобальні навички (~/.codex/skills/)"] G1["Особистий стиль комітів"] G2["Швидкий генератор ліцензій"] end subgraph ProjectScope ["Проєктні навички (.codex/skills/)"] P1["Архітектурний лінтер проєкту"] P2["Генератор DTO та міграцій БД"] P3["Чек-лист релізу сервісу"] end Dev["Розробник"] -->|Власні уподобання| GlobalScope Team["Команда в Git"] -->|Спільні стандарти| ProjectScope ``` ### Projekt-Skills (`.codex/skills/` oder `.agents/skills/`) Werden im Wurzelverzeichnis des Projekt-Repositories gespeichert und in Git versioniert. - **Zweck:** Standardisierung von Prozessen für das gesamte Entwicklungsteam. - **Vorteil:** Jeder Ingenieur (oder CI/CD-Runner), der das Repository klonnt, erhält sofort den identischen Satz an Agenten-Skills. ### Persönliche Skills (`~/.codex/skills/`) Befinden sich im Home-Verzeichnis des aktuellen Benutzers des Betriebssystems. - **Zweck:** Individuelle Werkzeuge, spezifisch für einen bestimmten Entwickler (z. B. persönlicher Assistent für die Notation in der Entwicklung). - **Vorteil:** Verfügbar in jedem Terminal, unabhängig vom aktiven Projekt. --- ## 6. Praktischer Workshop: Erstellung eines Code-Prüfungs-Skills mit `$skill-creator` Der einfachste und schnellste Weg, einen neuen Skill zu erstellen, ist die Nutzung des systemseitigen Meta-Tools `$skill-creator`, das in Codex integriert ist. ### Schritt 1. Initialisierung des Generators Im Codex-Dialogfeld rufen wir den Befehl auf: ```bash $skill-creator ``` Danach beschreiben wir den gewünschten Workflow in natürlicher Sprache: ```text Створи для мене проєктний скіл із назвою "pr-validator". Ціль: перевірити змінені файли у поточному pull request. Правила: 1. Запустити npm run lint та npm test. 2. Перевірити, чи додані unit-тести для нових модулів. 3. Заборонити агенту самостійно виправляти знайдені дефекти. 4. Результат вивести у вигляді таблиці з колонками: Файл, Рядок, Проблема, Рівень ризику. ``` ### Schritt 2. Überprüfung des generierten Artefakts Der Generator erstellt das Verzeichnis `.codex/skills/pr-validator/` und generiert die Datei `SKILL.md`: ```markdown --- name: pr-validator description: Validates pull request changes by running lint and test suites, checking test coverage for new modules, and returning an issue table without modifying code. --- Execution Steps: 1. Identify modified files using git diff against the target branch. 2. Execute "npm run lint" and capture any linter warnings or errors. 3. Execute "npm test" to ensure regression safety. 4. Verify whether newly created source files in src/ have corresponding test files in tests/. 5. Strict constraint: Do NOT modify any project files under any circumstances. 6. Present the audit findings in a markdown table: | File | Line | Issue | Severity | ``` ### Schritt 3. Testen des erstellten Skills in einer realen Session Öffnen Sie eine neue Codex-Session und testen Sie die Funktionsweise des erstellten Skills: ```bash $pr-validator перевір мою поточну гілку перед відкриттям PR ``` Stellen Sie sicher, dass der Agent den Linter ausgeführt hat, nicht versucht hat, Quellcodedateien zu bearbeiten, und eine Tabelle mit den Ergebnissen zurückgegeben hat. --- ## 7. Die Triade der Agenten-Fähigkeiten: Skill, Script und Tool Anfänger verwechseln häufig die Konzepte von Skill, Script und Tool (MCP). Sie ergänzen einander, lösen aber grundlegend unterschiedliche ingenieurtechnische Aufgaben. ```mermaid flowchart TD subgraph Triad ["Тріада архітектури автономного агента"] Skill["SKILL (Навичка)
'Мозок і регламент'
Пояснює послідовність, контекст та логіку"] Script["SCRIPT (Скрипт)
'Точний алгоритм'
Виконує детерміновану операцію на диску"] Tool["TOOL (Інструмент / MCP)
'Органи чуття та руки'
Надає доступ до API, терміналу, баз даних"] end Skill -->|Керує викликом| Script Skill -->|Використовує| Tool Script -->|Викликається через| Tool ``` ### Vergleichsmatrix der Triade | Komponente | Rolle im System | Ausführungsweise | Beispiel | | :--- | :--- | :--- | :--- | | **Skill (Fähigkeit)** | **Reglement & Denken** | Wird vom Modell gelesen und interpretiert | Anleitung zur Durchführung eines Sicherheitsaudits | | **Script (Skript)** | **Deterministische Rechenoperation** | Wird im OS über das Terminal ausgeführt | Bash-Skript zum Parsen von Git-Tags | | **Tool (Werkzeug)** | **Schnittstelle zum Zugriff auf die Umgebung** | Wird über den Mechanismus Tool Calling aufgerufen | MCP-Server zur Verbindung mit der GitHub API | > [!NOTE] > Ein Skill erklärt dem Agenten, **was** und **in welcher Reihenfolge** getan werden muss. Ein Script führt mathematische oder Dateibearbeitungsvorgänge schnell und garantiert aus. Ein Tool gewährt Berechtigungen zur Interaktion mit der Außenwelt. --- ## 8. Programmatic Control via Skills API and Versioning Neben der lokalen Arbeit mit Dateien bietet OpenAI eine spezialisierte **Skills API** zur programmatischen Steuerung von Skills in Cloud-Anwendungen und Backend-Systemen. ```bash # Створення нової навички через HTTP API curl https://api.openai.com/v1/skills \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "schema-migrator", "description": "Автоматична валідація та створення міграцій бази даних", "instructions": "Перевір схему Prisma, переконайся у відсутності drop column..." }' ``` ### Warum Skills-Versionierung wichtig ist 1. **Unveränderlichkeit der Produktionsumgebung (Immutability):** Jedes Update eines Skills erzeugt eine neue Version (`v1`, `v2`). Produktions-Pipelines binden sich an eine spezifische, fixierte Version, was unerwartete Ausfälle durch zufällige Änderungen verhindert. 2. **Sicheres Rollback:** Wenn eine aktualisierte Beschreibung zu Regressionen oder einer schlechteren Codegenerierungsqualität geführt hat, kann das Team sofort zur vorherigen Versionsnummer zurückkehren. 3. **A/B-Testing von Anweisungen:** Die Möglichkeit, gleichzeitig die Leistung zweier alternativer Skill-Revisionen bei realen Aufgaben zu vergleichen. --- ## 9. Sicherheit, Autonomiegrenzen und Bestätigungsregeln für Aktionen Ein Skill beeinflusst direkt, welche Operationen der Agent in Ihrem System ausführt. Daher müssen im Rumpf des Skills autonome und kontrollierte Aktionen klar voneinander getrennt sein. ```mermaid flowchart LR Action["Дія агента"] --> Decision{"Тип операції"} Decision -->|Безпечна: Read-Only| Auto["Автономне виконання без пауз
(Читання коду, запуск лінтера)"] Decision -->|Критична: Write / Network| Confirm["Запит підтвердження в інженера
(Видалення файлів, деплой)"] ``` ### Vertrauensstufen-Matrix :::tabs @tab Erlaubt ohne Bestätigung - Lesen von Quellcode-Dateien und Dokumentation. - Analyse von Build-Logs und Terminal-Fehlern. - Ausführung isolierter Unit-Tests im Read-Only-Modus. - Erstellung analytischer Berichte und Tabellen. @tab Erfordert zwingende Bestätigung - Änderung globaler Konfigurationsdateien (`package.json`, `.env`). - Löschen oder Überschreiben von Dateien im Repository. - Ausführung von Netzwerkrequests oder Senden von Daten an externe APIs. - Erstellen von Commits oder Pushen von Änderungen in ein Remote-Git-Repository. ::: > [!WARNING] > **Verbote nicht mehrfach duplizieren:** Vermeiden Sie die mehrfache Wiederholung von Phrasen wie „ändere nichts“ in jedem einzelnen Punkt. Es reicht aus, einmal zu Beginn des Abschnitts über Einschränkungen die verbotenen Operationen klar zu fixieren. Andernfalls wird der Agent übermäßig passiv und fragt selbst vor dem Lesen einer normalen Datei um Erlaubnis. --- ## 10. Zusammenfassende Cheatsheet und Checkliste für die Erstellung eines robusten Skills Speichern Sie diese Checkliste und orientieren Sie sich daran beim Design jedes neuen Skills. ### Schnelles Ingenieurs-Cheatsheet ```bash # ─── Робота з навичками в Codex ────────────────────────────────── $skill-creator # Запуск вбудованого майстра створення навичок $ <ваше завдання> # Явний детермінований виклик навички /skills # Перегляд списку доступних навичок у сесії # ─── Файлова структура проєкту ─────────────────────────────────── .codex/skills//SKILL.md # Проєктна навичка (для всієї команди) ~/.codex/skills//SKILL.md # Персональна навичка (для поточної машини) ``` ### Checkliste für die Release-Bereitschaft eines Skills - [ ] **Klarer Name:** Bis zu 64 Zeichen, Kleinschreibung, lateinische Buchstaben, mit Bindestrich (`kebab-case`). - [ ] **Informative Beschreibung:** Das Feld `description` enthält eine klare Formel für „Was macht der Skill“ und „Wann sollte er ausgeführt werden“. - [ ] **Knapper Rumpf:** Der Text der `SKILL.md` überschreitet 500 Zeilen nicht und enthält nur Projektspezifika. - [ ] **Schrittweise Pipeline:** Anweisungen sind in nummerierte Schritte ohne Mehrdeutigkeiten unterteilt. - [ ] **Sicherheitshorizont definiert:** Festgelegt, welche Dateien gelesen werden dürfen und für welche Aktionen zwingend eine Benutzerbestätigung erforderlich ist. - [ ] **Getestet in sauberer Session:** Der Skill wurde sowohl über den expliziten Aufruf `$name` als auch über die automatische Beschreibungszuordnung getestet.