SKILL: Operative Logistik-Erfahrung als Code

Dies ist eine 10-teilige Serie, die aufzeigt, wie Apidog Apidog CLI, ein Befehlszeilentool für API-Tests und API-Lebenszyklusmanagement, entwickelt hat. Lesen Sie die Beiträge der Reihe nach oder springen Sie zu jedem Beitrag, der Sie interessiert:

Ein SKILL ist nicht nur eine Befehlsreferenz. Es ist eine Bedienungsanleitung für KI-Agents: wann ein Befehl zu verwenden ist, welcher zuerst kommt, welche Felder nicht geraten werden sollten, wann validiert werden soll, wann zurückgelesen werden soll.

CLI allein ist nicht genug

CLI-Befehle geben einem Agent Ausführungsmacht.

Aber Macht ohne Urteilsvermögen führt zu Problemen:

Agents brauchen mehr als Befehle. Sie brauchen operatives Urteilsvermögen.

Was ist SKILL?

Ein SKILL ist eine Bedienungsanleitung, geschrieben für KI-Agents.

Es ist nicht:

• Eine einfache Befehlsliste
• Ein Referenzhandbuch
• Eine Hilfeseite

Es ist:

SKILL verleiht Agents operatives Urteilsvermögen.

Installation

SKILL ist eine Ergänzung zum Apidog CLI:

# SKILL für Ihren KI-Agent installieren
apidog skill install

Dies installiert 8 Begleit-Skills, die Agents helfen zu verstehen:

• Semantik von CLI-Befehlen
• Ressourcenstrukturen
• Aufgaben-Workflows
• Fehlerbehandlung
• Verifizierungsmuster

Warum SKILL wichtig ist: Verborgene Workflows

Der Agent muss immer noch wissen, wie Aufgaben in geschäftsübergreifende Ausführungsabläufe zerlegt werden sollen.

Diese Erfahrung kann nicht:

• Umfassend in Tool-Beschreibungen geschrieben werden (würde zu viel Kontext verbrauchen)
• Im Chat-Kontext verstreut sein (würde zwischen den Sitzungen verloren gehen)
• Vom Modell auswendig gelernt werden (produktspezifisch, kein allgemeines Wissen)

Verborgene Workflows und "geschäftliche Fallstricke" erfordern explizite Anweisungen.

Beispiel: Wartung eines Testszenarios

Betrachten Sie die Wartung eines komplexen Testszenarios.

Falscher Ansatz (Agent schreibt manuell von Grund auf):

Agent: "Ich werde die Testszenario-Struktur manuell erstellen"
Agent: Schreibt vollständiges Schritt-Array mit Assertions, Extraktoren, Prozessoren
Ergebnis: Feldfehler, falsche Vergleichsoperatoren, fehlende Pflichtfelder
CLI: Lehnt Schreiben ab oder erstellt unvollständiges Szenario

Korrekter Ansatz (in SKILL kodiert):

SKILL sagt nicht nur: "Es gibt einen Befehl test-scenario update."

Es sagt:

"Komplexe Szenarien sind nicht geeignet, um vollständige Strukturen von Grund auf manuell zu schreiben. Ein stabilerer Weg ist es, zuerst bestehende Endpunkt- oder Fallszenarien zu importieren, dann die vollständige Struktur zurückzulesen und schließlich lokale Änderungen vorzunehmen."

Die Befehle hinter der SKILL-Anleitung

Hier sind die tatsächlichen Befehle, die SKILL Agents zur Verwendung anleitet:

# Schritt 1: Schritte von Endpunkten importieren
apidog test-scenario import-steps <scenarioId> --project <projectId> \
  --source endpoint --ids <endpointIds> --sync manual

# Schritt 2: Mit vollen Details zurücklesen
apidog test-scenario get <scenarioId> --project <projectId> \
  --with-case-detail

# Schritt 3: Spezifische Teile aktualisieren (Agent generiert Update-JSON)

# Schritt 4: Vor dem Update validieren
apidog cli-schema validate test-scenario-update --file ./scenario-update.json

# Schritt 5: Update ausführen
apidog test-scenario update <scenarioId> --project <projectId> \
  --file ./scenario-update.json

# Schritt 6: Verifizierung ausführen
apidog run --project <projectId> --test-scenario <scenarioId>

SKILL sagt dem Agent, wann er jeden Befehl verwenden soll und warum.

Wichtige Erkenntnis: get--with-case-detail

SKILL betont:

"Verwenden Sie get--with-case-detail, um die reale Struktur zu erhalten, nicht um den Fall innerhalb der Schritte zu imaginieren."

Warum das wichtig ist:

Das Erhalten der realen Struktur verhindert auf Imagination basierende Updates.

Entwicklungsfähigkeit: SKILL kann sich ändern

Apidog SKILL ist eine entwicklungsfähige und versionierbare operative Erfahrung.

Warum das wichtig ist

Wie es funktioniert

Agents erhalten Schreibrechte für SKILL.

Wenn SKILL hinterherhinkt oder schwierig zu bedienen wird:

• Agent kann es ändern
• Agent kann Verbesserungen vorschlagen
• SKILL entwickelt sich durch Nutzung weiter

SKILL ist keine eingefrorene Dokumentation. Es ist lebendiger operativer Code.

Die Kompatibilitätsebene

Wir haben dies durch echte Fehler gelernt:

Problem erkannt:

Einige Szenarioschritte hatten bei sekundären Aktualisierungen erfolgreich die äußeren Schritte aktualisiert, aber interne HTTP-Fälle wurden nicht korrekt aktualisiert.

Grundursache:

• Interne Fall-Update-Marker erforderten eine spezielle Behandlung
• Agents wussten nichts über diese Marker
• Produktspezifische Semantik erforderte spezielle Flags

Lösung:

• Kompatibilitätslogik in CLI integriert
• CLI behandelt interne Marker automatisch
• Benutzer und Agents müssen interne Details nicht kennen

Die Bedeutung der Einschränkung ist in SKILL geschichtet:

SKILL sagt dem Agent, welche Befehle er verwenden soll. CLI handhabt die Produktsemantik hinter diesen Befehlen. Der Agent muss interne Marker nicht verstehen.

On-Demand-Laden

SKILL folgt dem gleichen Prinzip wie cli-schema:

Komplexität sollte durch Ausführung und Dokumentation absorbiert werden, nicht vollständig dem Modell ausgesetzt werden.

SKILL-Ansatz:

• Agent wärmt SKILL bei Bedarf auf
• SKILL wird geladen, wenn der Aufgabentyp identifiziert ist
• Nur relevante Workflow-Anweisungen gelangen in den Kontext

SKILL vs. Dokumentation

Die 8 Begleit-Skills

Apidog bietet 8 Begleit-Skills an:

Jeder SKILL enthält:

• Identifikation des Aufgabentyps
• Anleitung zur Befehlsreihenfolge
• Feldsicherheitsgrenzen
• Validierungsprüfpunkte
• Verifizierungsmuster

Was kommt als Nächstes

Nun, da wir alle drei Kernkomponenten etabliert haben:

• cli-schema validate – Qualitätsgate
• agentHints – Navigation zum nächsten Schritt
• SKILL – Workflow-Urteilsvermögen

Die nächste Frage ist:

Funktioniert das tatsächlich? Wie sind die Zahlen?

In Teil 6, Die Zahlen lügen nicht: 30% weniger Tool-Aufrufe, 25% weniger Tokens, werden wir quantitative Ergebnisse unserer internen Vergleiche teilen – und erklären, woher die Einsparungen kommen.

Wichtige Erkenntnisse

• CLI gibt Ausführungsmacht; SKILL gibt operatives Urteilsvermögen
• SKILL ist eine Bedienungsanleitung, keine Befehlsreferenz
• Verborgene Workflows erfordern explizite Anweisungen
• Schritte importieren → zurücklesen → lokal aktualisieren ist sicherer als manuelles Schreiben
• --with-case-detail verhindert auf Imagination basierende Updates
• SKILL ist entwicklungsfähig – Agents können es ändern
• CLI absorbiert Produktspezifika, SKILL leitet den Workflow
• On-Demand-Laden verhindert Kontextbelastung

Laden Sie Apidog herunter, um APIs in einem Arbeitsbereich zu entwerfen, zu mocken, zu testen und zu dokumentieren. Erfahren Sie mehr über Apidog CLI für Befehlszeilen-API-Tests, CI-Automatisierung und AI-Agent-Workflows.