Codex Skills: Erstellen, Ausführen und Verifizieren beim Code-Review

Der Skills-Mechanismus in Codex

Der Skills-Mechanismus, der in der offiziellen Dokumentation beschrieben wird, bindet Anweisungen und Vorlagen für spezialisierte Aufgaben an einen Agenten an, ohne den Systemkontext zu überlasten.

Ein Skill ist ein Verzeichnis mit einer obligatorischen SKILL.md-Datei. Im zugehörigen YAML-Frontmatter sind die Felder name und description erforderlich, während der Hauptteil die Regeln für das Modell enthält:

.agents/skills/boundary-review/
└── SKILL.md

Codex verwendet Progressive Disclosure: Beim Start wird ein kompakter Index der verfügbaren Skills erstellt. Der vollständige Text von SKILL.md wird vom Agenten erst in dem Moment eingelesen, in dem er sich für die Anwendung eines bestimmten Skills entscheidet.

Die Erkennung von Skills erfolgt über vier Ebenen:

1. Repository (REPO): .agents/skills im aktuellen Verzeichnis und aufwärts bis zum Git-Root.
2. Benutzer (USER): $HOME/.agents/skills.
3. Administrator (ADMIN): /etc/codex/skills.
4. System (SYSTEM): Systemverzeichnisse der Umgebung (bundled).

Der Aufruf erfolgt entweder explizit (über das Präfix $name) oder implizit (über die semantische Übereinstimmung der Anfrage mit description). Verfügbarkeit und Konflikte werden in der Datei config.toml geregelt.

Voraussetzungen und Isolation

Um das Szenario zu reproduzieren, sind erforderlich:

• Python 3;
• eine installierte und autorisierte Befehlszeilenschnittstelle Codex CLI.

Die Testdaten wurden am 2026-09-16 mit der Version Codex CLI 0.153.3 erfasst.

Alle Befehle werden in einem vorbereiteten lokalen Verzeichnis außerhalb eines Git-Repositorys ausgeführt. Da Textanweisungen in SKILL.md zwar das Verhalten des Modells steuern, aber keine Isolation auf Betriebssystemebene garantieren, erfolgt die Ausführung mit folgenden Flags:

• --ephemeral: verhindert das Speichern des Sitzungsstatus;
• --skip-git-repo-check: erlaubt die Ausführung in einem isolierten Ordner ohne Git;
• --sandbox read-only: beschränkt den Schreibzugriff des Prozesses auf Ebene der Ausführungsumgebung.

Die CLI kann globale Konfigurationen erben und Servicewarnungen zu Drittanbieter-Hooks ausgeben; daher stützt sich die tatsächliche Überprüfung ausschließlich auf die Leseereignisse des Ziel-Skills.

Erstellen des Skills boundary-review

Erstellen Sie das Skill-Verzeichnis im aktuellen Ordner:

mkdir -p .agents/skills/boundary-review

Speichern Sie folgenden Inhalt in .agents/skills/boundary-review/SKILL.md:

---
name: boundary-review
description: Review Python pagination code for boundary errors and show one minimal failing input. Use when asked to review pagination boundaries.
---
Read the provided Python file. Do not edit it. Begin your answer with BOUNDARY_REVIEW. Report a specific failing input, expected and actual result, and a minimal correction. Do not inspect files outside this project.

Die Textanweisung untersagt dem Modell das Ändern von Dateien und verlangt, die Antwort mit dem Signalmarker BOUNDARY_REVIEW zu beginnen sowie einen konkreten fehlerhaften Eingabewert anzugeben.

Fehlerhafte Testdatei

Erstellen Sie eine Datei pages.py mit einem typischen Off-by-One-Fehler bei der Berechnung der Seitenzahl:

def page_count(total, size):
    return total // size + 1

Unter den Bedingungen size > 0 und total >= 0 schlägt die Funktion bei Grenzwerten fehl: Bei total = 1 und size = 1 gibt sie 2 statt 1 zurück. Zudem liefert die Funktion für eine leere Liste mit total = 0 das Ergebnis 1.

Ausführung und Verifizierung der Aufrufe

Anfragen werden in einfachen Anführungszeichen übergeben, damit der Befehlszeilen-Interpreter das Zeichen $ nicht als Umgebungsvariable interpretiert.

1. Expliziter Aufruf nach Name

Starten Sie eine explizite Prüfung mit direkter Angabe des Skills:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review pages.py using $boundary-review'

Das Modell liefert folgendes Ergebnis:

BOUNDARY_REVIEW

Failing input:
page_count(1, 1)

Expected result: 1
Actual result: 2

Minimal correction:
def page_count(total, size):
    return (total + size - 1) // size

Das Vorhandensein des Markers BOUNDARY_REVIEW allein ist noch kein Beweis für das Laden von SKILL.md, da der Markertext auch aus dem Kontext der Anfrage generiert worden sein könnte. Beim tatsächlichen Durchlauf vom 2026-09-16 erfasste das Systemprotokoll den Befehlsaufruf zum Lesen der Datei .agents/skills/boundary-review/SKILL.md. Erst die Kombination aus dem Datei-Leseereignis im Protokoll, dem Präfix BOUNDARY_REVIEW und dem Gegenbeispiel page_count(1, 1) bestätigt die Ausführung der Zielanweisung.

2. Impliziter Aufruf nach Beschreibung

Formulieren Sie die Aufgabe in natürlicher Sprache ohne Nennung des Bezeichners $boundary-review:

codex exec --ephemeral --skip-git-repo-check --sandbox read-only 'Review the pagination boundaries in pages.py'

Im Protokoll dieses Durchlaufs wurde dank der Übereinstimmung zwischen der Formulierung in der Anfrage und dem Feld description ebenfalls ein Lesevorgang von .agents/skills/boundary-review/SKILL.md registriert. Der Agent erzeugte eine analog strukturierte Antwort mit dem Marker BOUNDARY_REVIEW und der Fehleranalyse für die Eingabe (1, 1).

Logikprüfung und Schritte für Leser

Prüfen wir das ursprüngliche Verhalten der Funktion mit dem lokalen Python-Interpreter:

python3 -c "from pages import page_count; print(page_count(1, 1))"

Der Befehl gibt 2 aus und bestätigt das Vorliegen des Fehlers.

Im Rahmen des Kontrolldurchlaufs vom 2026-09-16 blieb die ursprüngliche Datei pages.py unverändert; ein erneuter CLI-Lauf auf der modifizierten Datei wurde nicht durchgeführt. Die mathematische Korrektheit der vorgeschlagenen Formel (total + size - 1) // size für total >= 0 und size > 0 wurde anhand von Grenzwertsätzen überprüft:

• (0, 10) -> 0;
• (1, 1) -> 1;
• (10, 10) -> 1;
• (11, 10) -> 2.

Für eine manuelle Korrektur kann der Leser pages.py wie folgt anpassen:

def page_count(total, size):
    if total == 0:
        return 0
    return (total + size - 1) // size

Nach dem Speichern der Änderungen kann der Leser die Assertions überprüfen:

python3 -c "from pages import page_count; assert page_count(0, 10) == 0; assert page_count(1, 1) == 1; assert page_count(10, 10) == 1; assert page_count(11, 10) == 2; print('OK')"

Das erwartete Ergebnis der Befehlsausführung nach der manuellen Bearbeitung der Datei lautet: OK.

Fehlerbehebung

Wird ein Skill nicht gefunden oder nicht automatisch aufgerufen:

1. Dateipfad: Stellen Sie sicher, dass der Pfad relativ zum Arbeitsverzeichnis exakt .agents/skills/<skill-name>/SKILL.md lautet.
2. Registry-Aktualisierung: Wurden Dateien während einer aktiven Sitzung hinzugefügt, starten Sie den CLI-Prozess neu, um die Verzeichnisse neu einzulesen.
3. Konfigurationsblockade: Überprüfen Sie ~/.codex/config.toml. Wurde der Skill deaktiviert, blockiert ein Eintrag wie:

   [[skills.config]]
   path = "/полный/путь/к/.agents/skills/boundary-review/SKILL.md"
   enabled = false

   das Laden. Entfernen Sie den Block oder setzen Sie enabled = true.
4. Namenskonflikte: Wenn identische name-Werte auf Repository- und Benutzerebene existieren, können Prioritätsregeln zu Mehrdeutigkeiten führen.
5. Genauigkeit der description: Für implizite Aufrufe sollten wichtige Trigger („pagination boundaries“, „boundary errors“) möglichst am Anfang der Beschreibung stehen.
6. Drittanbieter-Skills: Wenn externe Pakete geladen werden müssen, dient das Hilfswerkzeug $skill-installer als Einstiegspunkt. Sämtliche Drittanbieter-Skills erfordern vor der Ausführung ein zwingendes manuelles Audit der SKILL.md-Dateien sowie des Verzeichnisses scripts/. Im Rahmen des beschriebenen Szenarios wurden keine Drittanbieter-Komponenten installiert.