Agent Skills für Softwareprozesse: Prompt zu Workflow

Ein Agent wiederholt bei jedem Coding-Auftrag dieselben Fragen, überspringt Prüfungen oder verwendet veraltete Projektregeln.

Die schnellste Lösung: Standardisieren Sie zuerst den Prozess, schreiben Sie ihn anschließend als versionierbaren Skill mit SKILL.md und verbinden Sie ihn erst danach mit einem orchestrierten Workflow. Agent Skills für Softwareprozesse vermitteln keine neue Modellkompetenz, sondern liefern passende SOPs, Werkzeuge, Prüfschritte und Referenzen genau dann, wenn sie gebraucht werden.

Zuletzt aktualisiert am 12.08.2026. Die Aussagen zu Skill-Struktur, dynamischem Laden und Berechtigungen wurden anhand der offiziellen Skills-Übersicht, der Claude-Code-Dokumentation zu Berechtigungen und der offiziellen Agent-Skills-Dokumentation geprüft.

Dieser Beitrag richtet sich an:

• Entwicklungsleiter, die das Verhalten von Coding Agents im Team vereinheitlichen möchten.
• Plattformingenieure, die Projektregeln, Prompts und Werkzeuge zentral pflegen.
• AI-Ingenieure, die Tests, Reviews und Releases in einen kontrollierten AI Agent Workflow einbinden wollen.

1. Trennen Sie Prompt, Skill und Workflow

Ein wiederholter Prompt ist zunächst nur eine Anweisung in einer Unterhaltung. Er kann beispielsweise lauten: „Analysieren Sie den Fehler, ändern Sie den Code, führen Sie die Tests aus und erstellen Sie eine Zusammenfassung.“

Das ist für einen einzelnen Auftrag ausreichend. Als Teamstandard hat dieser Ansatz jedoch vier Schwächen:

1. Keine belastbare Versionierung: Änderungen an Prompts werden oft in Chatverläufen, Notizen oder persönlichen Dateien gespeichert. Ein Pull Request mit nachvollziehbarer Änderungshistorie fehlt.
2. Uneinheitliche Ausführung: Zwei Entwickler formulieren denselben Auftrag unterschiedlich. Der Agent erhält dadurch andere Prioritäten, andere Dateien und teilweise andere Abnahmekriterien.
3. Schwache Wiederverwendung: Ein Prompt lässt sich nicht automatisch nach Aufgabe, Repository oder Fehlerklasse laden.
4. Keine klare Zuständigkeit: Wenn sich ein Testskript, ein API-Endpunkt oder eine Coding-Regel ändert, ist häufig unklar, wer den Prompt aktualisieren muss.

Ein Skill verlagert diese wiederkehrende Anleitung in eine strukturierte Ressource. Die offizielle Struktur besteht aus einem Verzeichnis mit einer SKILL.md und optionalen Unterordnern für Skripte, Referenzdokumente und Vorlagen. Der Agent lädt zunächst Metadaten und aktiviert den vollständigen Inhalt erst bei passender Aufgabe. Diese progressive Offenlegung hält allgemeine Sitzungen übersichtlicher. (claude.com)

Der Unterschied zum Workflow ist entscheidend:

• Prompt: beschreibt einen einzelnen Auftrag.
• Skill: beschreibt wiederverwendbares Verfahrenswissen.
• Workflow: verwaltet Zustand, Reihenfolge, Verzweigungen, Wiederholungen und Freigaben.

Kann ein Agent mit Skills tatsächlich den Teamprozess lernen?
Nein, wenn „lernen“ eine Änderung der Modellparameter meint. Ein Skill trainiert das Modell nicht dauerhaft. Er stellt Kontext und prozedurale Anweisungen bereit, die bei passenden Aufgaben erneut geladen werden. Das Verhalten kann dadurch konsistenter werden, bleibt aber von Modell, Toolzugriff, Projektzustand und Prüfmechanismen abhängig.

2. Beseitigen Sie verstreutes und veraltetes Prozesswissen

Viele Teams besitzen bereits eine Softwareentwicklungs-SOP. Das Problem ist ihre Verteilung:

• Coding-Regeln liegen in CONTRIBUTING.md.
• Testbefehle stehen in der CI-Konfiguration.
• API-Vorgaben liegen in einer separaten Dokumentation.
• Deployment-Schritte befinden sich in einem internen Wiki.
• Beispiele und bekannte Fehler werden in Chatkanälen geteilt.

Ein Agent kann diese Informationen nicht zuverlässig befolgen, wenn der Skill nur eine allgemeine Zusammenfassung enthält. Eine zusammengefasste Regel altert schneller als die Originaldatei. Außerdem entstehen widersprüchliche Quellen: Die SKILL.md verlangt einen Befehl, während das aktuelle Repository bereits einen anderen Testlauf nutzt.

Schreiben Sie deshalb nicht „Verwenden Sie immer unsere aktuellen Standards“. Verweisen Sie konkret auf die Dateien, die gelesen werden müssen:

1. Lies CONTRIBUTING.md und die relevante README-Datei.
2. Ermittle das verwendete Paketverwaltungssystem.
3. Prüfe die CI-Konfiguration auf den verbindlichen Testbefehl.
4. Verwende nur die API-Spezifikation aus references/api-contract.md.
5. Melde widersprüchliche Regeln, bevor du Dateien änderst.

Die description im Frontmatter sollte außerdem klar angeben, wann der Skill aktiviert werden soll. Nach dem offiziellen Skill-Creator-Leitfaden ist diese Beschreibung der wichtigste Mechanismus für die Auslösung. Der Skill sollte deshalb nicht nur seinen Zweck nennen, sondern auch typische Aufgaben und Begriffe abdecken. (github.com)

Wie schreiben Sie eine Softwareentwicklungs-SOP als Agent Skill?
Beginnen Sie mit einem beobachtbaren Auftrag, nicht mit einem abstrakten Ziel. „Qualität verbessern“ ist ungeeignet. „Jede Änderung an einem REST-Endpunkt anhand des API-Vertrags prüfen, Unit-Tests ausführen und bei Vertragsbruch stoppen“ ist überprüfbar.

Legen Sie zusätzlich eine Pflegeverantwortung fest:

• Repository-Verantwortliche pflegen Projektregeln.
• Das Plattformteam pflegt gemeinsame Skripte und Tooldefinitionen.
• Das Qualitätsteam kontrolliert Test- und Abnahmeregeln.
• Ein Änderungsdatum oder eine Versionsnummer zeigt, wann die Referenz zuletzt geprüft wurde.

So wird der Skill selbst zu einem normalen Engineering-Artefakt. Er gehört in die Versionskontrolle, benötigt Code-Review und sollte bei relevanten Änderungen durch automatisierte Tests laufen.

3. Ergänzen Sie jeden Skill um eine Abnahme

Ein häufiger Fehler besteht darin, den Agenten nur mit Handlungsschritten auszustatten:

1. Öffne die betroffenen Dateien.
2. Implementiere die Änderung.
3. Führe Tests aus.
4. Erstelle einen Commit.

Diese Reihenfolge beschreibt Aktivität, aber keine Qualität. Ein Softwareentwicklungs-Agent kann alle vier Schritte ausführen und trotzdem eine unvollständige oder riskante Änderung hinterlassen.

Ein belastbarer Skill benötigt mindestens fünf Kontrollpunkte:

• Eingangskriterien: Welche Dateien, Tickets oder Umgebungsvariablen müssen vorhanden sein?
• Änderungsgrenze: Welche Verzeichnisse dürfen bearbeitet werden?
• Testkriterien: Welche Befehle müssen erfolgreich abgeschlossen werden?
• Stop-Bedingungen: Wann darf der Agent nicht weiterarbeiten?
• Berichtsformat: Welche Fehler, Warnungen und offenen Punkte müssen gemeldet werden?

Beispiel für Stop-Bedingungen:

Stoppe die Aufgabe und melde den Grund, wenn:
- der API-Vertrag und der bestehende Code widersprüchliche Typen enthalten;
- ein benötigter Testbefehl nicht verfügbar ist;
- eine Datenbankmigration nicht reversibel geprüft werden kann;
- Dateien außerhalb des erlaubten Projektpfads betroffen wären;
- ein Test fehlschlägt und die Ursache nicht eindeutig eingegrenzt ist.

Wie prüfen Sie, ob ein AI Agent den Entwicklungsprozess einhält?
Nicht durch die Selbstauskunft des Agenten. Prüfen Sie das Ergebnis mit unabhängigen Signalen:

1. Wurde der erwartete Testbefehl tatsächlich ausgeführt?
2. Stimmen Exit-Code und gemeldeter Status überein?
3. Enthält der Diff nur erlaubte Dateien?
4. Wurde ein Testbericht mit Versionsstand und Zeitpunkt erzeugt?
5. Hat der Agent bei einer absichtlich eingebauten Regelverletzung korrekt gestoppt?
6. Ist eine menschliche Freigabe vor Merge oder Deployment erforderlich?

Der Skill-Creator von Anthropic empfiehlt für objektiv prüfbare Skills konkrete Testfälle und wiederholte Evaluationen. Das ist besonders relevant für Softwareaufgaben, weil Dateiveränderungen, Testausgaben und feste Formate automatisiert verglichen werden können. (github.com)

4. Begrenzen Sie Werkzeuge und Berechtigungen

Ein Skill kann beschreiben, welches Werkzeug verwendet werden soll. Er sollte jedoch nicht automatisch jede Berechtigung erhalten. Eine Anweisung wie „Führe das Deployment aus“ ist ohne Sicherheitsgrenze unvollständig.

Ordnen Sie Werkzeuge nach Risiko:

• Stufe A – lesend: Dateien lesen, suchen, Abhängigkeiten prüfen, Tests analysieren.
• Stufe B – kontrolliert schreibend: Änderungen im Arbeitsbaum, generierte Dateien, lokale Testdaten.
• Stufe C – extern wirksam: Git-Push, Datenbankänderungen, Cloud-Ressourcen, Veröffentlichungen.
• Stufe D – kritisch: Produktionszugriff, Löschvorgänge, Geheimnisverwaltung und irreversible Migrationen.

Claude Code unterscheidet unter anderem zwischen lesenden Dateioperationen, Shell-Befehlen und Dateiänderungen. Berechtigungsregeln können projektbezogen versioniert werden. Hooks können Werkzeugaufrufe vor der Ausführung prüfen und blockieren, ersetzen aber nicht die eigentlichen Deny-Regeln. (code.claude.com)

Hinweis aus der Praxis: Ein Skill darf erklären, wie ein Tool verwendet wird. Die Entscheidung, ob dieses Tool in einer bestimmten Umgebung verfügbar ist, gehört in die Laufzeitkonfiguration. Trennen Sie Anweisung, Berechtigung und Infrastruktur.

Für sensible Projekte sollten Sie den Agenten in einer isolierten Umgebung ausführen. Geeignete Maßnahmen sind:

• kurzlebige Entwicklungsumgebung statt Produktionsrechner;
• minimale Dateirechte;
• getrennte Zugangsdaten für Test- und Produktivsysteme;
• blockierter Zugriff auf .env-Dateien und private Schlüssel;
• Netzwerkfreigaben nur für benötigte Domains;
• Protokollierung aller Toolaufrufe;
• menschliche Freigabe vor extern wirksamen Änderungen.

Datenschutz und DSGVO müssen ebenfalls berücksichtigt werden. Ein Skill sollte keine Zugangsdaten in Referenzdateien enthalten. Prüfen Sie, welche Quelltexte, Logdaten und Tickets an ein Modell übertragen werden. Für Unternehmen ist nicht nur die technische Funktion wichtig, sondern auch Aufbewahrung, Zugriffskontrolle und Löschung der verarbeiteten Informationen.

5. Verschieben Sie komplexe Abläufe in einen Workflow

Ein SKILL.md eignet sich für prozedurale Anweisungen. Es ist kein Ersatz für eine vollständige Orchestrierungsplattform.

Sobald ein Ablauf mehrere Zustände besitzt, sollten Sie den Skill mit einem Workflow verbinden. Typische Zustände sind:

1. Auftrag angenommen.
2. Repository und Branch geprüft.
3. Plan erstellt.
4. Änderung implementiert.
5. Tests ausgeführt.
6. Review angefordert.
7. Korrekturschleife gestartet.
8. Freigabe erteilt.
9. Deployment vorbereitet.

Der Skill liefert dabei die lokale Verfahrenslogik. Der Workflow speichert den aktuellen Zustand und entscheidet, was bei Fehlern geschieht. Beispiel: Schlägt ein Unit-Test fehl, darf der Workflow den Agenten höchstens innerhalb einer definierten Korrekturschleife erneut starten. Nach der Grenze wird ein Mensch informiert. Ohne diese Zustandslogik versucht ein Agent oft weiterzuarbeiten, obwohl die Eingangsbedingungen nicht mehr stimmen.

Wann reicht eine einzelne SKILL.md nicht mehr aus?
Wenn der Text mehrere unabhängig wartbare Prozesse, viele Framework-Varianten oder umfangreiche Referenzdokumente enthält. Die offizielle Anleitung empfiehlt, große Inhalte in Referenzdateien auszulagern und nur bei Bedarf zu laden. Für den Skill-Creator wird außerdem eine kompakte Hauptdatei mit klaren Verweisen empfohlen. (github.com)

Eine sinnvolle Struktur sieht so aus:

feature-delivery/
├── SKILL.md
├── scripts/
│   ├── run-quality-gate.sh
│   └── collect-test-report.py
├── references/
│   ├── repository-rules.md
│   ├── api-contract.md
│   └── release-policy.md
└── assets/
    └── pull-request-template.md

Der Agent liest dann nicht jedes Dokument bei jedem Auftrag. Er lädt die relevante Referenz nur für die konkrete Aufgabe. Das reduziert veralteten Kontext und macht Änderungen gezielter.

6. Führen Sie die Umstellung in fünf Etappen durch

Schritt 1: Wiederholte Aufgaben erfassen
Sammeln Sie zwei bis vier Wochen lang typische Prompts. Gruppieren Sie sie nach Aufgabe: Fehleranalyse, Feature-Entwicklung, Testreparatur, Dokumentation, Release oder Incident-Nachbereitung. Messen Sie nicht nur die Anzahl der Prompts, sondern auch Korrekturen und manuelle Eingriffe.

Schritt 2: Eine verbindliche SOP schreiben
Entfernen Sie widersprüchliche Regeln. Definieren Sie Eingaben, erlaubte Dateien, Befehle, erwartete Ausgaben und Stop-Bedingungen. Wenn der Prozess nicht von einem neuen Teammitglied nachvollzogen werden kann, ist er noch nicht skillfähig.

Schritt 3: Den Skill erstellen
Legen Sie SKILL.md mit name und description an. Trennen Sie kurze Auslösebedingungen, Kernablauf und Referenzen. Verschieben Sie lange API-Dokumente, Vorlagen und Skripte in Unterverzeichnisse. Die offizielle Dokumentation beschreibt Skills als Verzeichnisse mit Anweisungen, Skripten und Ressourcen, die dynamisch geladen werden. (claude.com)

Schritt 4: Negativtests und Freigaben ergänzen
Testen Sie nicht nur den erfolgreichen Pfad. Erzeugen Sie absichtlich einen fehlenden Testbefehl, einen widersprüchlichen Vertrag und eine Datei außerhalb des erlaubten Pfads. Der Agent muss in allen drei Fällen stoppen oder eine Freigabe verlangen.

Schritt 5: Workflow und Umgebung anschließen
Erst jetzt integrieren Sie den Skill in CI/CD, Aufgabenwarteschlangen, Runner oder eine isolierte Entwicklungsumgebung. Dokumentieren Sie Retry-Grenzen, Zeitüberschreitungen, Protokolle und menschliche Übergabepunkte. Einen Überblick über isolierte Remote-Entwicklungsumgebungen können Sie in der VPSSpark-Übersicht zur Arbeitsumgebung einordnen.

7. Wählen Sie die passende Ausbaustufe

Die folgende Entscheidungstabelle verhindert, dass Sie zu früh eine komplexe Agentenplattform bauen:

Die Punktzahl ist ein Entscheidungsmodell, keine Leistungsangabe eines bestimmten Produkts. Wählen Sie die niedrigste Stufe, die Ihre Prozessrisiken abdeckt. Ein einzelner Skill ist sinnvoll, wenn die Aufgabe lokal, kurz und reversibel ist. Ein vollständiger Workflow ist notwendig, wenn mehrere Personen, Systeme oder Freigabestufen beteiligt sind.

8. Bewerten Sie den Reifegrad vor dem Ausbau

Bewerten Sie Ihren aktuellen Prozess mit drei Fragen:

• Wiederholen mindestens mehrere Teammitglieder denselben Prompt?
• Existieren feste Eingaben, Befehle und erwartete Ergebnisse?
• Können Sie einen Fehlerfall reproduzieren und objektiv bewerten?

Wenn nur die erste Frage mit Ja beantwortet wird, beginnen Sie mit einer SOP. Wenn alle drei Fragen mit Ja beantwortet werden, ist ein erster Skill sinnvoll. Wenn zusätzlich mehrere Übergaben, externe Systeme oder Freigaben nötig sind, bauen Sie einen Workflow.

Für eine belastbare Einführung sollten Entwicklung, Test und Plattform gemeinsam prüfen, ob der Ablauf ausführbar ist. Nach Änderungen an der Skill-Spezifikation oder an der Client-Unterstützung muss die Upgrade-Route erneut validiert werden. Die offiziellen Dokumentationen weisen darauf hin, dass Skills und Berechtigungen von der jeweiligen Laufzeit und Konfiguration abhängen. (code.claude.com)

9. Planen Sie die passende Ausführungsumgebung

Ein Skill löst keine Infrastrukturprobleme. Ein Agent benötigt weiterhin eine stabile Umgebung, passende Laufzeitversionen, Zugriff auf das Repository und kontrollierte Netzwerk- sowie Dateirechte.

Für einen kurzfristigen Test reicht eine isolierte Entwicklungsmaschine. Für wiederholbare Teamaufgaben benötigen Sie zusätzlich:

• reproduzierbare Abhängigkeiten;
• persistenten Arbeitsstand oder klar definierte Artefakte;
• SSH- und Repository-Zugriff mit minimalen Rechten;
• nachvollziehbare Testprotokolle;
• getrennte Umgebungen für Entwicklung, Prüfung und Veröffentlichung.

Wenn Sie dafür eine temporäre Remote-Umgebung benötigen, sollten Sie Regionen, Zugriffswege und Aufbewahrung der Daten vorab vergleichen. Die verfügbaren VPSSpark-Standorte für Remote-Entwicklung können als Ausgangspunkt für einen Testaufbau dienen. Für Fragen zu einer konkreten isolierten Umgebung steht außerdem der VPSSpark-Supportkontakt zur Verfügung.

Die Abgrenzung bleibt wichtig: Ein Skill kann einen Testbefehl angeben, aber nicht garantieren, dass die Abhängigkeiten installiert sind. Ein Workflow kann einen fehlenden Runner erkennen, aber nicht automatisch eine datenschutzrechtlich geeignete Umgebung herstellen. Diese Aufgaben gehören in die Plattform- und Betriebsarchitektur.

10. Entscheiden Sie zwischen Prompt, Skill und Workflow

Die Umstellung lohnt sich nicht bei jeder Aufgabe. Ein einmaliger Prototyp ohne wiederkehrende Regeln benötigt meist keinen Skill. Dagegen sollte ein Teamprozess mit festen Tests, Sicherheitsgrenzen und mehreren Beteiligten nicht dauerhaft in Chatprompts bleiben.

Der beste Übergang ist deshalb schrittweise:

1. Wiederholte Prompts sammeln.
2. Variationen und Fehlerquellen markieren.
3. SOP mit Eingangs- und Abnahmekriterien erstellen.
4. SOP als SKILL.md und Referenzstruktur versionieren.
5. Toolrechte und isolierte Ausführung definieren.
6. Negativtests und menschliche Gates ergänzen.
7. Erst bei mehreren Zuständen einen AI Agent Workflow einführen.

Der aktuelle Ansatz „Prompt plus manuelle Kontrolle“ hat drei reale Nachteile: Regeln sind schwer zentral zu pflegen, Prozessschritte driften zwischen Sitzungen auseinander und die Nachweise für Tests oder Berechtigungen bleiben lückenhaft. Für kurzfristige Versuche kann das genügen. Wenn Sie jedoch wiederholbare Softwareprozesse mit kontrollierter Remote-Ausführung benötigen, ist eine gemietete, klar abgegrenzte Entwicklungsumgebung von VPSSpark oft einfacher zu betreiben als ständig lokale Rechner, Zugriffsrechte und reproduzierbare Testumgebungen neu einzurichten. Für langfristige, dauerhaft hohe Last oder spezielle physische Schnittstellen bleibt eine eigene Infrastruktur die ehrlichere Wahl. Prüfen Sie daher zuerst Prozessdauer, Datenschutz, Persistenz und benötigte Rechte, bevor Sie mieten.