Ich möchte meinem Coding-Agenten bestimmte Dinge nicht bei jeder Aufgabe wieder sagen müssen. Vor dem Fertigmelden das Ergebnis tatsächlich ausprobieren, zum Beispiel. Dafür nutze ich Agent Skills als Prinzipien: kurze Anleitungen, die bei einer bestimmten Situation greifen und eine konkrete Entscheidung beeinflussen sollen.
In meinen Sessions bekomme ich inzwischen Rückmeldungen wie diese:
Prove It Works: exercised the built TUI at two real tmux sizes.
Oder:
Prove It Works führte zur Ausführung aller Shell-Beispiele im temporären Projekt; sie bestehen. Ein Agenten-A/B-Test wurde nicht durchgeführt.
Damit kann ich etwas anfangen. Der Agent nennt die Prüfung am laufenden Terminalprogramm. Ich kann im Verlauf nachsehen, ob er sie ausgeführt hat, und beurteilen, ob zwei Fenstergrößen für diese Änderung ausreichen.
In diesem Tutorial baust du ein kleines Setup dafür: einen Prinzipien-Skill, einen Index mit seinem Auslöser und eine Regel für die Rückmeldung. Am Ende prüfst du mit einer gewöhnlichen Aufgabe, ob der Agent das Prinzip von selbst aufgreift. Du brauchst ein Git-Repository, einen Editor und ein bereits eingerichtetes Claude Code oder Codex. Die Shell-Beispiele sind für macOS, Linux und WSL gedacht.
Was ein Prinzipien-Skill beitragen soll
Ein Beispiel aus der Entwicklung einer CLI: Der Agent ändert die Argumentverarbeitung, führt die Unit-Tests aus und meldet Erfolg. Du startest den dokumentierten Befehl. Die Ausgabe stimmt trotzdem nicht, weil der Einstiegspunkt die neue Option nicht weiterreicht.
Für solche Aufgaben möchte ich eine zusätzliche Gewohnheit etablieren: Vor dem Abschluss den Weg ausführen, den der Nutzer tatsächlich nimmt. Das Prinzip heißt bei mir Prove It Works. Bei einer CLI heißt das etwa, das gebaute Programm mit der neuen Option zu starten. Bei einer UI-Änderung gehört eine Prüfung der betroffenen Interaktion dazu.
Der Skill braucht deshalb einen erkennbaren Auslöser und eine Handlung:
- „Schreibe guten Code“ hilft mir als Anleitung wenig.
- „Bevor du eine Aufgabe fertigmeldest, prüfe das geänderte Verhalten am tatsächlichen Artefakt“ lässt sich an einer Session überprüfen.
Die Anregung für meine Prinzipien-Sammlung stammt aus Potetos pstack und dem Port von Michael Denyer. Daraus habe ich einzelne Prinzipien und die Regel übernommen, im Abschluss die beeinflusste Entscheidung zu benennen, weil mich die Liste der Prinzipien als leidenschaftlicher Deontologe direkt eingefangen hat. Utilitaristen werden damit nichts anfangen können :)
Das folgende Beispiel ist eine gekürzte, eigenständig formulierte Tutorial-Fassung.
1. Agent Skills im Projekt anlegen
Ich beginne im Projekt, damit die Dateien zusammen mit dem Code reviewbar sind. Die Codex-Dokumentation nennt .agents/skills/ als Projektpfad und beschreibt das Laden in zwei Stufen: zunächst Name und Beschreibung, bei Verwendung die vollständige Anleitung. Claude Code macht das genauso, nur aus .claude/skills/ heraus. Man kann beide Verzeichnisse symlinken, um nur eine Wahrheit an beide Agenten zu geben.
Wechsle ins Wurzelverzeichnis deines Repositories und lege das Verzeichnis an:
mkdir -p .agents/skills/principle-prove-it-works
Speichere den folgenden Inhalt als .agents/skills/principle-prove-it-works/SKILL.md:
---
name: principle-prove-it-works
description: "Apply before declaring a task done. Verify the changed behavior through the real artifact and report the observed result."
---
# Prove It Works
Before declaring a task done, exercise the behavior the user will rely on.
A successful build alone does not show that the changed behavior works.
## Apply it
1. Identify the behavior changed by this task.
2. Choose a direct check: run the CLI command, exercise the UI interaction,
or inspect the generated document.
3. Run that check and compare the actual result with the expected result.
4. Report what you ran and what you observed.
5. If the check is blocked, state the blocker and what remains unverified.
Scale the check to the change. Prefer an existing command or workflow.
Do not invent a successful result or add unrelated checks.
Die Beschreibung nennt die Situation, in der die Anleitung gebraucht wird. Der Text darunter erklärt die Handlung und lässt Platz für das Projekt: Welcher Befehl relevant ist, hängt von deiner Aufgabe ab.
Ich lasse das Beispiel bei den gemeinsamen Feldern name und description.
In Claude Code blende ich die Prinzipien im Slash-Menü aus, sodass Claude sie sieht und verwenden kann, aber ich davon nicht bei manueller Aktivierung belästigt werde. Diese Hintergrund-Skills haben zusätzlich user-invocable: false in den Metadaten gesetzt, siehe Claude-Code-Dokumentation. Das ist eine Claude-Code-Erweiterung; für dieses gemeinsame Setup brauchst du sie nicht.
2. Den Auslöser in einen kurzen Index schreiben
Skills werden bei Bedarf geladen. Ich möchte mich bei längeren Aufgaben aber nicht allein darauf verlassen, dass der Agent aus der Skill-Beschreibung im richtigen Moment auf ein relevantes Prinzip schließt.
Darum nutze ich zusätzlich zur Skill-Beschreibung einen Index in den Projektanweisungen. Er fordert den Agenten ausdrücklich auf, bei der passenden Situation die vollständige Anleitung zu lesen. So kann ich diese Arbeitsweise selbst formulieren und ändern.
Lege den Index neben den Skills an:
mkdir -p .agents/skills/principles
Speichere dies als .agents/skills/principles/INDEX.md:
# Principles
When a situation below occurs, including during an ongoing task,
read the referenced skill in full and apply it without waiting to be asked.
In your final reply, name each principle that changed a decision and
state the concrete choice it changed. Name only principles whose
SKILL.md you read in this session. Omit principles that changed nothing.
- **Prove It Works.** Before declaring a task done, verify the changed
behavior through the real artifact. Read
`.agents/skills/principle-prove-it-works/SKILL.md`.
Die Rückmelderegel gehört dazu. Wenn der Agent am Ende nur „Prinzipien berücksichtigt“ schreibt, erfahre ich nichts über seine Arbeit. Ich will wissen, welche Entscheidung daraus folgte. Beim CLI-Beispiel wäre das: zusätzlich das gebaute Programm mit dem neuen Argument ausführen und dessen Ausgabe prüfen.
Mit diesem einen Prinzip kannst du das Setup bereits ausprobieren. Eine größere Sammlung macht die erste Fehlersuche unnötig aufwendig (aber die Arbeit interessanter).
3. Den Index in Claude Code oder Codex einbinden
Der Zielzustand im Repository sieht so aus, wenn du beide Werkzeuge nutzt:
.agents/skills/
principle-prove-it-works/SKILL.md
principles/INDEX.md
.claude/skills/
principle-prove-it-works -> ../../.agents/skills/principle-prove-it-works
AGENTS.md
CLAUDE.md
(Aktuelle Claude-Code-Versionen können auch AGENTS.md als Projektanweisung lesen, wenn im Arbeitsverzeichnis oder darüber keine projektbezogene CLAUDE.md oder CLAUDE.local.md liegt. Details stehen in der Dokumentation zu AGENTS.md. Das Setup unten zeigt beide Dateien.)
Claude Code
Claude Code lädt Projekt-Skills aus .claude/skills/. Für unser Beispiel verlinkst du den vorhandenen Skill-Ordner dorthin:
mkdir -p .claude/skills
ln -s ../../.agents/skills/principle-prove-it-works \
.claude/skills/principle-prove-it-works
Führe ln -s einmal aus. Falls das Ziel bereits existiert, schau dir den vorhandenen Eintrag an, bevor du ihn änderst. Der relative Link zeigt vom Verzeichnis .claude/skills/ zurück zur Projektwurzel und dann in .agents/skills/.
Ergänze in deiner bestehenden CLAUDE.md diese Zeile; vorhandene Projektregeln bleiben stehen:
@.agents/skills/principles/INDEX.md
Claude Code unterstützt solche Datei-Imports in CLAUDE.md. Relative Importpfade beziehen sich auf die Datei mit dem Import. Hier liegt CLAUDE.md in der Projektwurzel.
Starte anschließend eine neue Session aus dieser Projektwurzel. Der Index gehört nun zu den Startanweisungen; die vollständige Prinzipien-Anleitung wird bei Bedarf gelesen.
Codex
Für Codex liegt der Skill bereits im passenden Projektverzeichnis .agents/skills/. Hier brauchst du keinen zweiten Link.
Ergänze in deiner bestehenden AGENTS.md einen ausdrücklichen Leseauftrag:
## Principles
Before starting work, read `.agents/skills/principles/INDEX.md` in full and follow its instructions for the rest of the session.
The path above is relative to the repository root.
Codex bekommt diesen Auftrag über die Projektanweisungen aus AGENTS.md. Der Agent soll dann den Index per Werkzeug lesen. Bei Claude Codes @-Import wird die Datei schon beim Laden der Anweisungen eingebunden. Hier kommt der Index durch einen zusätzlichen Lesezugriff in den Kontext.
Du kannst den Leseauftrag auch in deiner user-globalen ~/.codex/AGENTS.md hinterlegen. Verwende dort einen absoluten Pfad zum global installierten Index, etwa /home/dein-name/.agents/skills/principles/INDEX.md auf Linux oder /Users/dein-name/.agents/skills/principles/INDEX.md auf macOS. Auch die Skill-Pfade im globalen Index müssen vom jeweiligen Projekt aus auffindbar sein; die relativen Projektpfade aus diesem Tutorial müsstest du dafür anpassen.
Starte Codex danach neu aus der Projektwurzel. Falls dort eine AGENTS.override.md liegt, prüfe zuerst deren Inhalt: Codex bevorzugt sie auf derselben Verzeichnisebene gegenüber AGENTS.md.
4. Erst die Verkabelung prüfen
Bevor du eine echte Aufgabe startest, kontrolliere die Dateien:
test -r .agents/skills/principle-prove-it-works/SKILL.md && echo "Skill lesbar"
test -r .agents/skills/principles/INDEX.md && echo "Index lesbar"
test -r .claude/skills/principle-prove-it-works/SKILL.md && echo "Claude-Link lesbar"
Diese Befehle prüfen Pfade und Lesbarkeit. Ob das Werkzeug die Anweisungen geladen hat, klärst du als Nächstes in einer frischen Session:
Welche Anweisung gilt hier vor dem Fertigmelden einer Aufgabe?
Lies die zugehörige vollständige Anleitung und nenne ihren Dateipfad.
Ändere keine Dateien.
Erwartet ist ein Verweis auf Prove It Works und das Lesen der angelegten SKILL.md. Sieh dir die Werkzeugaufrufe im Verlauf an. Eine passende Antwort allein könnte der Agent schon aus dem Index ableiten.
Wenn das scheitert, prüfe zuerst Arbeitsverzeichnis, Dateinamen und den Link. Bei Codex kontrollierst du außerdem, ob der Leseauftrag in der verwendeten AGENTS.md steht und der Agent den referenzierten Index tatsächlich gelesen hat. Wenn mehrere Projektregeln dieselbe Situation unterschiedlich regeln, kläre den Widerspruch, bevor du die Skill-Beschreibung verlängerst.
5. Die Anwendung an einer gewöhnlichen Aufgabe prüfen
Der vorige Prompt hat das Lesen ausdrücklich verlangt. Jetzt interessiert dich, ob der Agent bei einer passenden Aufgabe selbst daran denkt.
Nimm dafür eine kleine Änderung in einem entbehrlichen Testprojekt. Bei einer vorhandenen CLI könnte der Auftrag so aussehen:
Ergänze für den bestehenden Befehl eine Option --version.
Sie soll die Versionsnummer aus der vorhandenen Projektmetadatei ausgeben.
Der Prompt nennt das Prinzip nicht. Lege vor dem Lauf fest, was du beobachten möchtest: Der Agent soll das fertige Programm mit --version ausführen und die tatsächliche Ausgabe mit der Versionsnummer in den Metadaten vergleichen. Der genaue Aufruf hängt von deinem Projekt ab.
Bewerte anschließend drei Dinge getrennt anhand des Transkripts:
| Beobachtung | Was sie dir zeigt |
|---|---|
Der Agent liest die SKILL.md. |
Die Anleitung wurde in dieser Session geladen. |
| Er führt das geänderte Programm aus und vergleicht die Ausgabe. | Die gewünschte Prüfung hat stattgefunden. |
| Er nennt im Abschluss das Prinzip und die konkrete Prüfung. | Die Rückmelderegel wurde befolgt. |
Ein möglicher Abschluss sähe so aus:
Prove It Works: Ich habe zusätzlich zu den Tests das gebaute CLI mit
--versiongestartet und die Ausgabe mit der Versionsnummer in den Projektmetadaten verglichen. Beide stimmen überein.
Das ist ein Beispiel für eine Rückmeldung, kein Messergebnis dieses Tutorials. Ob die Aussage stimmt, prüfst du an den ausgeführten Befehlen und ihren Ausgaben. Ein Prinzipienname im Abschluss kann fehlende Prüfung nicht ersetzen.
Für einen Vergleich wiederholst du denselben Auftrag in frischen Kopien desselben Ausgangsstands: einmal mit dem Setup, einmal ohne Index und Prinzipien-Skill. Vorhandene globale Regeln können den Vergleich beeinflussen. Halte Werkzeug, Modell, Auftrag und Ausgangscode möglichst gleich und protokolliere die drei Beobachtungen pro Lauf.
Ein einzelner erfolgreicher Lauf gibt dir einen ersten Hinweis. Er belegt noch keine verlässliche Verhaltensänderung über unterschiedliche Aufgaben und lange Sessions hinweg. In meinen eigenen Versuchen und Sessions gefällt mir vor allem, dass die Rückmeldung das Verhalten leichter besprechbar macht.
Die Auflistung angewandter Prinzipien am Ende gefällt mir dabei unerwartet gut. Sie hilft mir bei der Besinnung auf das ‚plumbing‘ mit Agenten, und wenn die Liste fehlt, fällt mir das mittlerweile auf.
Das gilt auch für Subagenten. Ein Review-Subagent nannte nach der Prüfung einer größeren Änderung am perception-Modul drei Prinzipien für die Modularisierung:
Principles applied: Model the Domain (one event channel instead of two reporting paths; one cue shape instead of three structs), Minimize Reader Load (count the layers between „hostility began“ and the „!“), Redesign from First Principles (ask what the aggro effort would have built if pursuit had been a day-one requirement).
Die Liste macht sichtbar, welche Datenformen, Wege durch den Code und Architekturannahmen er hinterfragt hat. Ob seine zwei Änderungsvorschläge vor dem Merge tragen, muss ich am Code und an den Tests prüfen; die Abschlussmeldung allein belegt das nicht.
Weitere Prinzipien aus wiederkehrenden Korrekturen ableiten
Wenn der erste Skill funktioniert, nimm eine Korrektur, die du deinem Agenten wiederholt gibst. Beschreibe zuerst die Situation und dann die gewünschte Handlung. Zwei Beispiele:
- Der Agent startet beim Debugging sofort mit einem Patch → Fix Root Causes: zuerst den Fehler reproduzieren und die Ursache eingrenzen.
- Mehrere Reparaturen beruhen auf derselben Annahme und scheitern an derselben Prüfung → Attack the Premise: die gemeinsame Annahme aufschreiben und vor dem nächsten Patch prüfen.
Für jedes neue Prinzip brauchst du wieder eine eigene SKILL.md und einen Eintrag im Index. Der Leseauftrag in AGENTS.md kann dabei unverändert bleiben.
Ich würde die Sammlung erst vergrößern, wenn ich das bisherige Prinzip in mehreren Sessions beobachtet habe. Bleibt die Handlung aus, hilft mir die Rückmeldung bei der Fehlersuche. Verursacht die Anleitung regelmäßig unnötige Prüfungen, grenze ich ihren Geltungsbereich ein.
Natürlich kann man auch mal 10 neue Prinzipien bauen und schauen, wie das emergente Verhalten sich ändert :)
In meinem Artikel über Skills gegen die Amnesie des Agenten geht es um wiederkehrende Anleitungen allgemein. Warum ich meine Skills nicht wiederverwende beschreibt, warum ich solche Texte zunächst am konkreten Einsatz ausrichte.
Für den Einstieg reicht das Setup aus diesem Beitrag.
- Lege das Prinzip an,
- gib dem Agenten eine kleine reale Aufgabe und
- prüfe im Verlauf, ob er die zusätzliche Handlung tatsächlich ausgeführt hat.