Communitygithub.com

aetox-skills/create-agent

Scope-first Agent Design Skill — Kläre den Scope, bevor du den Agenten baust.

Was ist create-agent?

Dieser Skill zwingt zu einem disziplinierten, scope-zentrierten Designprozess für KI-Agenten. Bevor du irgendeinen Prompt, eine Konfiguration oder eine Tool-Bindung schreibst, wird ein strukturiertes Scope-Interview durchgeführt. Die Tiefe des Interviews hängt von der Komplexität des zu entwerfenden Agenten ab. Es geht nicht darum, Prompts zu schreiben, sondern den Scope zu validieren. Das Ergebnis ist ein validiertes **Agent Spec** – ein Bauplan, den andere KI oder Menschen nutzen können, um den Agenten korrekt zu erstellen. Das System definiert 8 Dimensionen für jeden Agenten (Archetyp, Persönlichkeit, Fähigkeiten, I/O, Ökosystem, Gedächtnis, Lebenszyklus, Risiko/Metriken) und vier Tiefenstufen (Quick, Standard, Deep, Critical). Standardmäßig wird die leichteste Stufe „Quick" verwendet. Der Skill enthält einen Archetypenkatalog mit Minimierungslisten, die festlegen, welche Dimensionen für welchen Archetypen ausführlich, kurz oder übersprungen werden sollen. Kritische Regeln sind unter anderem: „Scope before build", „Infer first, ask later" und „Minimize round-trips". Der Skill setzt auf Cursor, Claude Code, Codex und andere KI-Agenten-Plattformen und liefert einen validierten Spezifikationsausgabe – immer, auch auf der Quick-Ebene.

Funktioniert mit✓Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add aetox-skills/create-agent

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Agent erstellen

Zweck

KI-Agenten mit einer Scope-zentrierten Disziplin entwerfen. Bevor du irgendeinen Prompt, eine Konfiguration oder eine Tool-Bindung schreibst, musst du ein strukturiertes Scope-Interview bestehen. Die Tiefe des Interviews hängt von der Komplexität des zu entwerfenden Agenten ab.

Dies ist kein Skill zum Prompt-Schreiben. Es ist ein Scope-Validierungs-Skill. Die Ausgabe ist ein validiertes Agent Spec – ein Bauplan, den eine andere KI oder ein Mensch nutzen kann, um den Agenten korrekt zu erstellen.

Jedes Agent Spec definiert 8 Dimensionen:

Archetyp → Persönlichkeit → Fähigkeiten → I/O → Ökosystem → Gedächtnis → Lebenszyklus → Risiko/Metriken

Eiserne Regeln

  1. Scope vor Build — Kein Code, kein Prompt, keine Tool-Konfiguration bis der Scope validiert ist. Keine Ausnahmen.

    Korrekturbefugnis: Gilt nur für draft/spec assumptions — Korrigiere Annahmen im Spec, die der Benutzer übersehen hat (fehlende Abhängigkeit, Widerspruch, Sicherheitsrisiko) sofort, ohne vorher zu fragen. Sage nur, was angepasst wurde und warum. Ändere niemals echte Dateien, Konfigurationen, Tools oder Workflows ohne Genehmigung. Hole eine Genehmigung ein, wenn die korrekte Lösung ein neues Tool oder eine Änderung eines bestehenden Workflows erfordert – aber wenn es gesunder Menschenverstand ist, das Spec zu korrigieren, mach es einfach.

  2. Minimale ausreichende Tiefe — Standardmäßig Quick. Steigere auf Standard/Deep/Critical nur, wenn explizite Signale auftauchen. Beginne nicht mit Standard.

  3. Erst ableiten, dann fragen — Bevor du eine Frage stellst, versuche die Antwort aus dem Kontext, der Codebasis, bestehenden Agenten und dem, was der Benutzer bereits gesagt hat, abzuleiten. Frage nur nach dem, was wirklich unklar bleibt.

  4. Codebasis zuerst — Wenn die Antwort auf eine Frage in der Konfiguration, Dokumentation oder in bestehenden Agenten existiert – suche sie dort. Frage nicht. Greenfield-Ausnahme: Wenn es keine Codebasis gibt (keine index.md, AGENTS.md, opencode.jsonc oder bestehenden Agenten), überspringe den Codebasis-Scan und gehe direkt zum Interview.

  5. Rundgänge minimieren — Spec ableiten → Entwurf präsentieren → Benutzer markieren lassen. Frage nur einzeln nach echten Lücken, die der Entwurf nicht schließen kann. Wirf niemals 10 Fragen auf einmal.

  6. Empfehlen, nicht offen lassen — Jede Frage muss eine empfohlene Antwort enthalten. Gib etwas, auf das reagiert werden kann.

  7. Spec muss genehmigt sein — Baue niemals, bis das Agent Spec explizit genehmigt ist. Für die Quick-Ebene gilt die Bestätigung des abgeleiteten Specs durch den Benutzer als Genehmigung. Dokumentiere es als Status: Genehmigt via Quick.

  8. Auf Signal stoppen — Wenn der Benutzer „genug" oder „stopp" sagt – stoppe. Diskutiere nicht, dränge nicht auf mehr.

  9. Ein Agent Spec ausgeben — Jede Sitzung produziert ein validiertes Spec, selbst auf der Quick-Ebene.


Agent-Archetyp-System

Agenten folgen Mustern basierend auf ihrem Archetyp. Verwende diese Tabelle, um den richtigen Archetyp auszuwählen und zu verstehen, welche Interview-Domänen fokussiert oder übersprungen werden sollen.

Archetyp-Katalog

#ArchetypKernzweckStandard-PersönlichkeitTypische ToolsVorgeschlagene Ebene
🛠️SystemAutomatisieren, konfigurieren, wartenPraktisch, prägnant, direktCLI, Dateisystem, Docker, gitQuick → Standard
🎨KreativEntwerfen, visuell, BewegungAusdrucksstark, detailorientiertTailwind, GSAP, Bild-APIsQuick → Standard
💻EntwicklerCode, Architektur, debuggenTechnisch, präzise, gründlichMCPs, Linter, TestrunnerQuick → Deep
📝SchreiberDokumentieren, schreiben, organisierenKlar, strukturiert, geduldigObsidian, Markdown, SucheQuick
🔬SpezialistTiefe einzelne DomäneAutoritativ, akribischDomänenspezifisches CLI/MCPQuick → Deep
🎯OrchestratorKoordinieren, delegieren, verwaltenSystematisch, prozessorientiertAgentenliste, ÜbergabeprotokollQuick → Critical
🔍ForscherSuchen, analysieren, synthetisierenNeugierig, analytisch, gründlichExa, Firecrawl, Web-ToolsQuick
🎮SpielSpielspezifisches VerhaltenVerspielt, anpassungsfähigSpiel-API, Bot-FrameworkQuick → Deep

Archetyp-Minimierungsliste

Nicht „überspringen", sondern sagen, welche Domäne kurz sein sollte oder bei Offensichtlichkeit übersprungen werden kann.

Es gibt 3 Stufen:

  • Tief — alles fragen
  • Kurz — nur 1-2 Fragen stellen, dann zusammenfassen
  • Bei Offensichtlichkeit überspringen — nicht fragen, wenn der gesunde Menschenverstand es sagt (z.B. Schreiber → Gedächtnis = sitzungsbasiert)
ArchetypKurzBei Offensichtlichkeit überspringenTief
SystemIdentität, I/OGedächtnisFähigkeiten, Ökosystem
KreativRisiko/Metriken, LebenszyklusGedächtnisIdentität, I/O, Persönlichkeit
EntwicklerLebenszyklusIdentitätFähigkeiten, Ökosystem, I/O
SchreiberÖkosystemRisiko/Metriken, GedächtnisIdentität, I/O
SpezialistI/O, Lebenszyklus—Fähigkeiten, Risiko/Metriken
Orchestrator——Alle Domänen
ForscherLebenszyklus, PersönlichkeitGedächtnisFähigkeiten, I/O, Identität
SpielÖkosystemRisiko/MetrikenFähigkeiten, I/O, Persönlichkeit

Entwickler + Identität: Kurz bedeutet nicht überspringen – Identität (Frontmatter) muss noch vorhanden sein, da sie festlegt, wann der Agent aufgerufen wird. Mache es nur kurz (1-2 Sätze).

Archetyp-Auswahl

Empfehle beim Interview einen Archetyp basierend auf dem Zweck des Agenten. Wenn mehrere Archetypen passen, wähle den dominanten und notiere sekundäre.

Beispiel: "Das klingt nach einem Entwickler-Archetyp mit etwas Spezialisten-Überschneidung.
         Gemäß Minimierungsliste: Lebenszyklus = kurz, Identität = kurz (nur Frontmatter),
         Fokus Tiefe auf Fähigkeiten + Ökosystem."

Tiefen-Ebenen-System

Nicht jeder Agent benötigt die gleiche Tiefe. Dieser Skill definiert 4 Ebenen. Standardmäßig Quick. Beginne leicht, steigere nur, wenn Signale es erfordern.

Ebene 1 — Quick       (ableiten → bestätigen → bauen, bei Unsicherheit nachfragen)
                       │                          ← STANDARD
Ebene 2 — Standard    (Entwurf präsentieren → Benutzer markiert → genehmigen)
                       │
Ebene 3 — Tief        (Standard + Ökosystem-Karte + Abhängigkeitsverfolgung)
                       │
Ebene 4 — Kritisch    (Tief + Risikomodell + Kostenmodell + Sicherheitsgates)

Ebenenauswahl

SignalQuickStandardTiefKritisch
Agent ist neu oder geändert (1-2 Fähigkeiten), Scope klar✅———
Bestehender Agent, kleine Änderung✅———
Neuer Agent, einzelner Zweck, keine Abhängigkeiten—✅——
Neuer Agent, 1-2 externe Integrationen—✅✅—
Agent in Multi-Agent-Ökosystem——✅✅
Verarbeitet Zahlungen / Authentifizierung / PII———✅
Wird in Produktion eingesetzt———✅
Hohe Token-Kosten pro Aufruf———✅
Sicherheits- oder Compliance-Implikationen———✅
Archetyp = Orchestrator———✅
Archetyp = Spezialist——✅—

Standardmäßig Quick. Steigere nur, wenn explizite Signale vorhanden sind.

Eskalationsregel: Wenn du während eines Interviews auf einer niedrigeren Ebene Signale entdeckst, die eine höhere Ebene rechtfertigen, eskaliere explizit:

Eskalationshinweis:
  Auslöser: [was du gefunden hast]
  Nachweis: [wo du es gefunden hast]
  Risiko des Verbleibs: [warum die niedrigere Ebene unsicher ist]

Ebene 1 — Quick

Für einfache Agenten und kleine Änderungen. Leite das Spec aus dem Kontext ab, bestätige es mit dem Benutzer, baue es. Kein vollständiges Interview, kein separates Genehmigungs-Gate.

Überdenke diese Ebene nicht zu sehr. Wenn du unsicher bist, beginne trotzdem hier – die Komplexität wird während der Ableitung sichtbar. Steigere, wenn Signale auftauchen.

Einstiegskriterien

  • Agent ist neu (1-2 Fähigkeiten) oder vorhanden mit kleinen Änderungen.
  • Keine externen Integrationen über das bereits Vorhandene hinaus.
  • Keine Multi-Agent-Koordination.
  • Kein Sicherheits-, Kosten- oder Compliance-Risiko.
  • Anforderungen sind klar genug, dass ein 8-Domänen-Interview wie Over-Engineering wirken würde.

Prozess

1. Spec aus Kontext ableiten    ← Aus dem, was der Benutzer gesagt hat + Codebasis + bestehende Agenten lesen
2. Mini-Spec präsentieren        ← Festes Format unten verwenden
3. Benutzer markiert             ← „Sag mir, was geändert werden soll"
   Wenn die Markierung trivial ist (1-2 Wörter, kleiner Formatfehler)
     → Kann sofort gebaut werden
   Wenn die Markierung strukturell ist (Fähigkeit hinzufügen, Tool ändern, Grenze ändern)
     → Überarbeitetes Mini-Spec präsentieren → Benutzer bestätigt → Bauen
4. Bauen

Mini-Spec-Format (Fest)

## Quick Spec: [Name]

Job: [Ein Satz – „Was tun, für wen, um was zu erreichen"]
Fähigkeiten:
  - [Aktion 1]
  - [Aktion 2]
Grenzen:
  - [Was nicht tun]
Befugnis: [Nur Lesen / Vorschlagen / Im Rahmen ändern / Ausführen / Autonom]
Tools: [Tool / MCP / Keine benötigt]
Genehmigung: [Bestätigt via Quick / Überarbeitet & Bestätigt]

Verwende die Datei templates/quick-spec.md als echte Vorlage. Verkürze oder überspringe diese Felder nicht – wenn ein Feld offensichtlich ist, schreibe „—" (frage den Benutzer nicht). Wenn ein bestehender Agent geändert wird → verwende das gleiche Format, zeige aber nur die geänderten Felder.

Beispiel

Benutzer: "Ich möchte einen Agenten, der mir Mails zusammenfasst"

Ableiten:
  Archetyp: Schreiber
  Fähigkeit: E-Mail lesen → Aufzählungszusammenfassung
  Tools: Gmail MCP (bereits vorhanden)
  Ökosystem: Arbeitet mit Steward

Mini-Spec präsentieren:
  ## Quick Spec: mail-summarizer

  Job: Gmail lesen → Mike jeden Morgen eine Aufzählungszusammenfassung geben
  Fähigkeiten:
    - E-Mails vom Gmail MCP lesen → als Aufzählungspunkte zusammenfassen
    - Nach Absender / Betreff trennen
  Grenzen:
    - Nicht auf E-Mails antworten, keine E-Mails löschen
  Befugnis: Nur Lesen (nur lesen)
  Tools: Gmail MCP (bereits vorhanden)
  Genehmigung: —

  "Deutsch/Englisch? Alle E-Mails oder nur bestimmte Themen?"

Benutzer: "Englisch, alle E-Mails, kein Log"
  (triviale Markierung — Sende Bauen)

Bauen.
  ## Quick Spec: mail-summarizer
  ...
  Befugnis: Nur Lesen
  Genehmigung: Bestätigt via Quick

Ebene 2 — Standard

Für neue Agenten und signifikante Änderungen. Steigere auf Standard, wenn Quick nicht ausreicht (komplexe Integrationen, Ökosystem-Auswirkungen oder unklarer Scope).

Prozess

1. Absichts-Gate       → Wiederholen, Archetyp identifizieren, Benutzer + Ziel + Einschränkung
2. Codebasis-Scan     → index.md, opencode.jsonc, AGENTS.md, bestehende Agenten lesen
                       (wenn nicht vorhanden → Greenfield: überspringen, direkt Entwurf präsentieren)
3. Archetyp-Match     → Archetyp auswählen, Minimierungsliste anwenden
4. Entwurf präsentieren → Vollständiges Spec aus bekanntem Kontext ableiten → 1-seitigen Entwurf präsentieren
                       Nur nach Unsicherheiten fragen (nicht alles einzeln)
5. Benutzer markiert     → Benutzer bearbeitet / fügt hinzu / entfernt aus Entwurf
6. Iterieren (falls nötig) → Wenn Lücken vorhanden → überarbeiteten Entwurf präsentieren
7. Spec vorschlagen      → Vollständiges Agent Spec (siehe templates/agent-spec.md)
8. Genehmigungs-Gate     → Benutzer genehmigt vor dem Bauen

Scope-Interview (8 Domänen)

Für Quick-Ebene: Alle überspringen – ableiten + von Anfang an bestätigen

Für Standard+:

  1. Entwurfs-Spec aus vorhandenem Kontext ableiten → 1-seitigen Entwurf dem Benutzer präsentieren
  2. Benutzer liest und markiert (ändert/hinzufügt/löscht)
  3. Verwende die Checkliste unten, um zu prüfen, ob etwas fehlt – frage nur nach Dingen, die der Entwurf nicht abdeckt
  4. Wende die Archetyp-Minimierungsliste an – kurz / bei Offensichtlichkeit überspringen / tief gemäß Archetyp

Frage niemals Punkt für Punkt aus der Checkliste – präsentiere zuerst den Entwurf, frage nur nach Lücken.

Domäne 1: Identität & Zweck

  • Name — Wie heißt der Agent? (vorschlagen, wenn unbenannt)

  • Archetyp — Welcher Archetyp laut Katalog?

  • Rolle — Ein klarer Satz: "Dieser Agent [tut X] für [Benutzer Y], damit [Z]."

  • Persona —

    FeldWasBeispiel
    Tonformell / informell / technisch / verspielt / autoritativ / warm"technisch, aber zugänglich"
    Beispielsatzein echter Satz, den der Agent sagt"Lass mich die Konfiguration prüfen... Gefunden. Das Problem liegt in Zeile 42."

    Empfehle immer eine Persona.

    "Ich schlage einen technischen, aber zugänglichen Ton vor –
     präzise bei Fakten, entspannt im Gespräch."
    
  • Kennt den Kontext — Was muss der Agent wissen, bevor er arbeitet?

  • Engste Aufgabe — Was ist die kleinste sinnvolle Definition seiner Rolle?

Domäne 2: Fähigkeiten & Grenzen

  • Fähigkeiten — Kernaktionen, nach Priorität geordnet. Jede Fähigkeit beinhaltet:

    • Beschreibung (1 Satz)
    • Auslöser (wie wird diese Fähigkeit aufgerufen?)
    • Erwartete Ausgabe (wie sieht Erfolg aus?)
    • Fehlermodus (was passiert, wenn es nicht funktioniert?)
  • Grenzen — Explizite Liste, was der Agent niemals tun darf. Formatiere jede als Kritische Regel mit Szenario:

    Regel: Niemals Dateien außerhalb des Projektverzeichnisses ändern.
    Szenario: Benutzer fragt "repariere meine Desktop-Einstellungen" – Agent hat Dateisystemzugriff.
    Konsequenz: Höflich ablehnen, Scope-Einschränkung erklären.
    
  • Tool-Zuordnung — Für jede Fähigkeit bestimmen, welche Tools benötigt werden. Tue dies nachdem die Fähigkeiten und Grenzen klar sind.

    Fähigkeit: "Dokumentation durchsuchen"
    ↓
    Codebasis nach vorhandenen Tools durchsuchen → Exa MCP gefunden (Websuche)
    ↓
    Vorschlagen: "Wissensabruf via Exa MCP (bereits konfiguriert).
              Falls Exa nicht verfügbar ist, Rückfall auf Websuche via Firecrawl."
    

    Regel: Schlage ein spezifisches Tool vor, wenn bereits eines in der Codebasis existiert. Schlage nur eine Kategorie vor, wenn kein vorhandenes Tool passt. Aber: Wenn das vorhandene Tool nicht zu den Anforderungen passt (z.B. lokale Dokumentsuche benötigt, aber nur Exa Websuche vorhanden) – erzwinge keine Fehlanpassung. Markiere es als Teilweise Passung oder Lücke und schlage eine passendere Kategorie vor.

    ✅ "Verwendet Exa MCP für die Websuche – bereits konfiguriert"
    ✅ "Exa MCP ist für die Websuche vorhanden, aber die Arbeitssuche sollte
        Obsidian + grep verwenden – ist eine teilweise Passung für externe Suche"
    ✅ "Keine vorhandene Vektordatenbank gefunden. Benötigt ein semantisches Suchtool
        wie Chroma oder Qdrant."
    ❌ "Benötigt ein Tool zum Wissensabruf" (vage – Exa existiert, verwende es)
    ❌ "Verwendet Exa MCP für alles" (Fehlanpassung – Exa ist nicht für die lokale Suche geeignet)
    

    Tool-Kategorien (Referenz für Lücken):

    Wissensabruf         → Suche, Vektordatenbanken, Dokumentspeicher, Web Scraping
    Codeausführung       → Sandboxes, Interpreter, Compiler, Linter
    Kommunikation        → E-Mail, Messaging, Benachrichtigungen, Webhooks
    Systemoperationen    → Datei-I/O, Prozessmanagement, Netzwerk, Registry
    Datenverarbeitung    → ETL, Transformation, Validierung, Speicherung
    Visuell/Kreativ      → Bildgenerierung, Layout-Engines, Animation
    Überwachung          → Logs, Metriken, Tracing, Benachrichtigungen
    KI/LLM               → Modell-APIs, Embeddings, RAG-Pipelines, Vektordatenbanken
    Testen               → Testrunner, Coverage, Mocking, E2E-Browser
    
  • Skills — Welche Skills werden für den Agenten benötigt? (Dieser Teil wurde in der ursprünglichen Eingabe abgeschnitten, aber die Übersetzung wird entsprechend fortgesetzt.)

    ...


Vorlagen


Verwendung

Dieser Skill wird in jeder Sitzung automatisch aktiviert, wenn über die Erstellung oder Änderung eines Agenten gesprochen wird. Der Skill arbeitet nach den definierten Ebenen und Regeln, wobei die Scope-Validierung immer vor dem Bauen erfolgt.

Verwandte Skills