SamuelChien/mega-skills-collection

Agentenentwicklung für Claude Code Plugins

Übersicht

Agenten sind autonome Unterprozesse, die komplexe, mehrschrittige Aufgaben unabhängig voneinander bearbeiten. Das Verständnis der Agentenstruktur, der Auslösebedingungen und des System-Prompt-Designs ermöglicht die Erstellung leistungsstarker autonomer Fähigkeiten.

Schlüsselkonzepte:

• Agenten sind FÜR autonome Arbeit, Befehle sind FÜR nutzerinitiierte Aktionen
• Markdown-Dateiformat mit YAML-Frontmatter
• Auslösung über das description-Feld mit Beispielen
• Der System-Prompt definiert das Agentenverhalten
• Anpassung von Modell und Farbe

Agenten-Dateistruktur

Vollständiges Format

---
name: agent-identifier
description: Verwenden Sie diesen Agenten, wenn [Auslösebedingungen]. Beispiele:

<example>
Context: [Situationsbeschreibung]
user: "[Nutzeranfrage]"
assistant: "[Wie der Assistent antworten und diesen Agenten verwenden soll]"
<commentary>
[Warum dieser Agent ausgelöst werden sollte]
</commentary>
</example>

<example>
[Weiteres Beispiel...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

Sie sind [Agentenrollenbeschreibung]...

**Ihre Kernaufgaben:**
1. [Aufgabe 1]
2. [Aufgabe 2]

**Analyseprozess:**
[Schritt-für-Schritt-Arbeitsablauf]

**Ausgabeformat:**
[Was zurückgegeben werden soll]

Frontmatter-Felder

name (erforderlich)

Agentenbezeichner, der für Namensräume und den Aufruf verwendet wird.

Format: nur Kleinbuchstaben, Zahlen, Bindestriche Länge: 3-50 Zeichen Muster: Muss mit alphanumerischem Zeichen beginnen und enden

Gute Beispiele:

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

Schlechte Beispiele:

• helper (zu allgemein)
• -agent- (beginnt/endet mit Bindestrich)
• my_agent (Unterstriche nicht erlaubt)
• ag (zu kurz, < 3 Zeichen)

description (erforderlich)

Definiert, wann Claude diesen Agenten auslösen soll. Dies ist das wichtigste Feld.

Muss enthalten:

1. Auslösebedingungen ("Verwenden Sie diesen Agenten, wenn...")
2. Mehrere <example>-Blöcke, die die Verwendung zeigen
3. Context, user-Anfrage und assistant-Antwort in jedem Beispiel
4. <commentary>, das erklärt, warum der Agent ausgelöst wird

Format:

Verwenden Sie diesen Agenten, wenn [Bedingungen]. Beispiele:

<example>
Context: [Szenariobeschreibung]
user: "[Was der Nutzer sagt]"
assistant: "[Wie Claude antworten soll]"
<commentary>
[Warum dieser Agent geeignet ist]
</commentary>
</example>

[Weitere Beispiele...]

Best Practices:

• 2-4 konkrete Beispiele einfügen
• Proaktive und reaktive Auslösung zeigen
• Unterschiedliche Formulierungen derselben Absicht abdecken
• Begründung im commentary erläutern
• Konkret angeben, wann der Agent NICHT verwendet werden soll

model (erforderlich)

Welches Modell der Agent verwenden soll.

Optionen:

• inherit - Gleiches Modell wie das übergeordnete Element verwenden (empfohlen)
• sonnet - Claude Sonnet (ausgewogen)
• opus - Claude Opus (leistungsfähigste, teuer)
• haiku - Claude Haiku (schnell, günstig)

Empfehlung: Verwenden Sie inherit, es sei denn, der Agent benötigt spezifische Modellfähigkeiten.

color (erforderlich)

Visueller Identifikator für den Agenten in der Benutzeroberfläche.

Optionen: blue, cyan, green, yellow, magenta, red

Richtlinien:

• Wählen Sie unterschiedliche Farben für verschiedene Agenten im selben Plugin
• Verwenden Sie konsistente Farben für ähnliche Agententypen
• Blau/Cyan: Analyse, Überprüfung
• Grün: Erfolgsorientierte Aufgaben
• Gelb: Vorsicht, Validierung
• Rot: Kritisch, Sicherheit
• Magenta: Kreativ, Generierung

tools (optional)

Beschränkt den Agenten auf bestimmte Tools.

Format: Array von Toolnamen

tools: ["Read", "Write", "Grep", "Bash"]

Standard: Wenn weggelassen, hat der Agent Zugriff auf alle Tools

Best Practice: Beschränken Sie die Tools auf das notwendige Minimum (Prinzip der geringsten Rechte)

Häufige Tool-Sets:

• Nur-Lese-Analyse: ["Read", "Grep", "Glob"]
• Codegenerierung: ["Read", "Write", "Grep"]
• Testen: ["Read", "Bash", "Grep"]
• Vollzugriff: Feld weglassen oder ["*"] verwenden

System-Prompt-Design

Der Markdown-Text wird zum System-Prompt des Agenten. Schreiben Sie in der zweiten Person und sprechen Sie den Agenten direkt an.

Struktur

Standardvorlage:

Sie sind [Rolle] mit Spezialisierung auf [Domäne].

**Ihre Kernaufgaben:**
1. [Primäre Aufgabe]
2. [Sekundäre Aufgabe]
3. [Zusätzliche Aufgaben...]

**Analyseprozess:**
1. [Schritt eins]
2. [Schritt zwei]
3. [Schritt drei]
[...]

**Qualitätsstandards:**
- [Standard 1]
- [Standard 2]

**Ausgabeformat:**
Geben Sie Ergebnisse in diesem Format aus:
- [Was einschließen]
- [Wie strukturieren]

**Grenzfälle:**
Behandeln Sie diese Situationen:
- [Grenzfall 1]: [Wie zu behandeln]
- [Grenzfall 2]: [Wie zu behandeln]

Best Practices

✅ TUN:

• Schreiben Sie in der zweiten Person ("Sie sind...", "Sie werden...")
• Seien Sie spezifisch in Bezug auf Aufgaben
• Geben Sie einen schrittweisen Prozess an
• Definieren Sie das Ausgabeformat
• Fügen Sie Qualitätsstandards hinzu
• Adressieren Sie Grenzfälle
• Bleiben Sie unter 10.000 Zeichen

❌ NICHT TUN:

• Schreiben Sie in der ersten Person ("Ich bin...", "Ich werde...")
• Seien Sie vage oder allgemein
• Lassen Sie Prozessschritte weg
• Lassen Sie das Ausgabeformat undefiniert
• Überspringen Sie Qualitätshinweise
• Ignorieren Sie Fehlerfälle

Agenten erstellen

Methode 1: KI-gestützte Generierung

Verwenden Sie dieses Prompt-Muster (aus Claude Code extrahiert):

Erstellen Sie eine Agentenkonfiguration basierend auf dieser Anfrage: "[IHRE BESCHREIBUNG]"

Anforderungen:
1. Extrahieren Sie die Kernabsicht und Verantwortlichkeiten
2. Entwerfen Sie eine Experten-Persönlichkeit für die Domäne
3. Erstellen Sie einen umfassenden System-Prompt mit:
   - Klaren Verhaltensgrenzen
   - Spezifischen Methodiken
   - Behandlung von Grenzfällen
   - Ausgabeformat
4. Erstellen Sie einen Bezeichner (Kleinbuchstaben, Bindestriche, 3-50 Zeichen)
5. Schreiben Sie eine Beschreibung mit Auslösebedingungen
6. Fügen Sie 2-3 <example>-Blöcke hinzu, die die Verwendung zeigen

Geben Sie JSON zurück mit:
{
  "identifier": "agentenname",
  "whenToUse": "Verwenden Sie diesen Agenten, wenn... Beispiele: <example>...</example>",
  "systemPrompt": "Sie sind..."
}

Konvertieren Sie dies dann in das Agenten-Dateiformat mit Frontmatter.

Siehe examples/agent-creation-prompt.md für die vollständige Vorlage.

Methode 2: Manuelle Erstellung

1. Wählen Sie einen Agentenbezeichner (3-50 Zeichen, Kleinbuchstaben, Bindestriche)
2. Schreiben Sie die Beschreibung mit Beispielen
3. Wählen Sie das Modell (normalerweise inherit)
4. Wählen Sie eine Farbe zur visuellen Identifikation
5. Definieren Sie die Tools (falls der Zugriff eingeschränkt werden soll)
6. Schreiben Sie den System-Prompt mit der obigen Struktur
7. Speichern Sie die Datei als agents/agentenname.md

Validierungsregeln

Identifikator-Validierung

✅ Gültig: code-reviewer, test-gen, api-analyzer-v2
❌ Ungültig: ag (zu kurz), -start (beginnt mit Bindestrich), my_agent (Unterstrich)

Regeln:

• 3-50 Zeichen
• Nur Kleinbuchstaben, Zahlen, Bindestriche
• Muss mit alphanumerischem Zeichen beginnen und enden
• Keine Unterstriche, Leerzeichen oder Sonderzeichen

Beschreibungsvalidierung

Länge: 10-5.000 Zeichen Muss enthalten: Auslösebedingungen und Beispiele Optimal: 200-1.000 Zeichen mit 2-4 Beispielen

System-Prompt-Validierung

Länge: 20-10.000 Zeichen Optimal: 500-3.000 Zeichen Struktur: Klare Aufgaben, Prozess, Ausgabeformat

Agentenorganisation

Plugin-Agentenverzeichnis

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

Alle .md-Dateien in agents/ werden automatisch erkannt.

Namensräume

Agenten werden automatisch in Namensräume eingeteilt:

• Einzelnes Plugin: agentenname
• Mit Unterverzeichnissen: plugin:unterverzeichnis:agentenname

Agenten testen

Testen der Auslösung

Erstellen Sie Testszenarien, um zu überprüfen, ob der Agent korrekt auslöst:

1. Schreiben Sie den Agenten mit spezifischen Auslösebeispielen
2. Verwenden Sie ähnliche Formulierungen wie in den Testbeispielen
3. Überprüfen Sie, ob Claude den Agenten lädt
4. Stellen Sie sicher, dass der Agent die erwartete Funktionalität bietet

System-Prompt testen

Stellen Sie sicher, dass der System-Prompt vollständig ist:

1. Geben Sie dem Agenten eine typische Aufgabe
2. Überprüfen Sie, ob er den Prozessschritten folgt
3. Stellen Sie sicher, dass das Ausgabeformat korrekt ist
4. Testen Sie die im Prompt erwähnten Grenzfälle
5. Bestätigen Sie, dass die Qualitätsstandards eingehalten werden

Kurzreferenz

Minimaler Agent

---
name: einfacher-agent
description: Verwenden Sie diesen Agenten, wenn... Beispiele: <example>...</example>
model: inherit
color: blue
---

Sie sind ein Agent, der [X tut].

Prozess:
1. [Schritt 1]
2. [Schritt 2]

Ausgabe: [Was bereitgestellt werden soll]

Zusammenfassung der Frontmatter-Felder

Feld	Erforderlich	Format	Beispiel
name	Ja	kleinbuchstaben-bindestriche	code-reviewer
description	Ja	Text + Beispiele	Verwenden wenn... ...
model	Ja	inherit/sonnet/opus/haiku	inherit
color	Ja	Farbname	blue
tools	Nein	Array von Toolnamen	["Read", "Grep"]

Best Practices

TUN:

• ✅ Fügen Sie 2-4 konkrete Beispiele in die Beschreibung ein
• ✅ Schreiben Sie spezifische Auslösebedingungen
• ✅ Verwenden Sie inherit für das Modell, es sei denn, es besteht ein spezifischer Bedarf
• ✅ Wählen Sie geeignete Tools (geringste Rechte)
• ✅ Schreiben Sie klare, strukturierte System-Prompts
• ✅ Testen Sie die Agentenauslösung gründlich

NICHT TUN:

• ❌ Verwenden Sie generische Beschreibungen ohne Beispiele
• ❌ Lassen Sie Auslösebedingungen weg
• ❌ Geben Sie allen Agenten die gleiche Farbe
• ❌ Gewähren Sie unnötigen Toolzugriff
• ❌ Schreiben Sie vage System-Prompts
• ❌ Überspringen Sie das Testen

Zusätzliche Ressourcen

Referenzdateien

Eine ausführliche Anleitung finden Sie unter:

• references/system-prompt-design.md - Vollständige System-Prompt-Muster
• references/triggering-examples.md - Beispielformate und Best Practices
• references/agent-creation-system-prompt.md - Der genaue Prompt aus Claude Code

Beispieldateien

Arbeitsbeispiele in examples/:

• agent-creation-prompt.md - KI-gestützte Agentengenerierungsvorlage
• complete-agent-examples.md - Vollständige Agentenbeispiele für verschiedene Anwendungsfälle

Dienstprogrammskripte

Entwicklungstools in scripts/:

• validate-agent.sh - Validiert die Agenten-Dateistruktur
• test-agent-trigger.sh - Testet, ob der Agent korrekt auslöst

Implementierungsablauf

So erstellen Sie einen Agenten für ein Plugin:

1. Definieren Sie den Agentenzweck und die Auslösebedingungen
2. Wählen Sie die Erstellungsmethode (KI-gestützt oder manuell)
3. Erstellen Sie die Datei agents/agentenname.md
4. Schreiben Sie das Frontmatter mit allen erforderlichen Feldern
5. Schreiben Sie den System-Prompt gemäß den Best Practices
6. Fügen Sie 2-4 Auslösebeispiele in die Beschreibung ein
7. Validieren Sie mit scripts/validate-agent.sh
8. Testen Sie die Auslösung mit realistischen Szenarien
9. Dokumentieren Sie den Agenten in der Plugin-README

Konzentrieren Sie sich auf klare Auslösebedingungen und umfassende System-Prompts für den autonomen Betrieb.