Agent-almanac create-agent

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/de/skills/create-agent" ~/.claude/skills/pjt222-agent-almanac-create-agent-289ad3 && rm -rf "$T"

manifest: i18n/de/skills/create-agent/SKILL.md

source content

Neuen Agenten erstellen

Eine Claude-Code-Subagenten-Persona mit einem klar fokussierten Zweck, kuratierten Werkzeugen, zugewiesenen Skills und vollstaendiger Dokumentation definieren, gemaess der Agentenvorlage und Registry-Konventionen.

Wann verwenden

Hinzufuegen eines neuen Spezialisten-Agenten zur Bibliothek fuer eine noch nicht abgedeckte Domain
Umwandlung eines wiederkehrenden Workflows oder Promptmusters in eine wiederverwendbare Agenten-Persona
Erstellen eines domaenspezifischen Assistenten mit kuratierten Skills und eingeschraenkten Werkzeugen
Aufteilen eines zu breiten Agenten in fokussierte, Single-Responsibility-Agenten
Entwurf eines neuen Teammitglieds vor der Zusammenstellung eines Multi-Agenten-Teams

Eingaben

Erforderlich: Agentenname (Kleinbuchstaben-Kebab-Case, z.B.
```
data-engineer
```
)
Erforderlich: Einzeilige Beschreibung des primaeren Zwecks des Agenten
Erforderlich: Zweckerklaerung, die das Problem beschreibt, das der Agent loest
Optional: Modellauswahl (Standard:
```
sonnet
```
; Alternativen:
```
opus
```
,
```
haiku
```
)
Optional: Prioritaetsstufe (Standard:
```
normal
```
; Alternativen:
```
high
```
,
```
low
```
)
Optional: Liste von Skills aus
```
skills/_registry.yml
```
zur Zuweisung
Optional: MCP-Server, die der Agent benoetigt (z.B.
```
r-mcptools
```
,
```
hf-mcp-server
```
)

Vorgehensweise

Schritt 1: Agenten-Persona entwerfen

Eine klare, fokussierte Identitaet fuer den Agenten waehlen:

Name: Kleinbuchstaben-Kebab-Case, beschreibend fuer die Rolle. Mit einem Substantiv oder Domain-Qualifier beginnen:
```
security-analyst
```
,
```
r-developer
```
,
```
tour-planner
```
. Generische Namen wie
```
helper
```
oder
```
assistant
```
vermeiden.
Zweck: Ein Absatz, der das spezifische Problem erklaert, das dieser Agent loest. Fragen: "Was tut dieser Agent, was kein bestehender Agent abdeckt?"
Kommunikationsstil: Domain beachten. Technische Agenten sollten praezise und zitatschwer sein. Kreative Agenten koennen explorativer sein. Compliance-Agenten sollten formal und pruefungsorientiert sein.

Vor dem Fortfahren auf Ueberschneidungen mit den bestehenden 53 Agenten pruefen:

grep -i "description:" agents/_registry.yml | grep -i "<eigene-domain-schluesselwoerter>"

Erwartet: Kein bestehender Agent deckt dieselbe Nische ab. Falls ein bestehender Agent teilweise ueberlappt, erwaegen diesen zu erweitern anstatt einen neuen zu erstellen.

Bei Fehler: Falls ein Agent mit erheblicher Ueberschneidung existiert, entweder dessen Skills-Liste erweitern oder den neuen Agenten eingrenzen, um ihn zu ergaenzen statt zu duplizieren.

Schritt 2: Werkzeuge auswaehlen

Den minimalen Satz an Werkzeugen waehlen, die der Agent benoetigt. Prinzip der minimalen Berechtigungen anwenden:

Werkzeugset	Wann verwenden	Beispielagenten
`[Read, Grep, Glob]`	Nur-Lese-Analyse, Pruefung, Auditierung	code-reviewer, security-analyst, auditor
`[Read, Grep, Glob, WebFetch]`	Analyse plus externe Lookups	senior-researcher
`[Read, Write, Edit, Bash, Grep, Glob]`	Vollstaendige Entwicklung — Code erstellen/aendern	r-developer, web-developer, devops-engineer
`[Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch]`	Entwicklung plus externe Recherche	polymath, shapeshifter

Bash

nicht fuer Agenten einbeziehen, die nur Code analysieren.

WebFetch

oder

WebSearch

nicht einbeziehen, wenn der Agent nicht genuinen Bedarf hat, externe Ressourcen abzufragen.

Erwartet: Die Werkzeugliste enthaelt nur Werkzeuge, die der Agent tatsaechlich in seinen primaeren Workflows verwenden wird.

Bei Fehler: Die Faehigkeitsliste des Agenten ueberpruefen — falls eine Faehigkeit kein Werkzeug erfordert, das Werkzeug entfernen.

Schritt 3: Modell waehlen

Das Modell basierend auf der Aufgabenkomplexitaet auswaehlen:

sonnet
(Standard): Die meisten Agenten. Gutes Gleichgewicht zwischen Reasoning und Geschwindigkeit. Fuer Entwicklung, Pruefung, Analyse und Standard-Workflows verwenden.
opus
: Komplexes Reasoning, mehrstufige Planung, differenziertes Urteil. Fuer Senior-Level-Agenten, Architekturentscheidungen oder Aufgaben mit tiefer Domainexpertise verwenden.
haiku
: Einfache, schnelle Antworten. Fuer Agenten verwenden, die unkomplizierte Lookups, Formatierungen oder Vorlagenausfuellungen durchfuehren.

Erwartet: Das Modell entspricht den kognitiven Anforderungen der primaeren Anwendungsfaelle des Agenten.

Bei Fehler: Im Zweifel

sonnet

verwenden. Nur auf

opus

upgraden, wenn Tests eine unzureichende Reasoning-Qualitaet aufzeigen.

Schritt 4: Skills zuweisen

Die Skills-Registry durchsuchen und fuer die Domain des Agenten relevante Skills auswaehlen:

# Alle Skills in einer Domain auflisten
grep -A3 "domain-name:" skills/_registry.yml

# Nach Skills mit Schluesselbegriffen suchen
grep -i "keyword" skills/_registry.yml

Die Skills-Liste fuer das Frontmatter erstellen:

skills:
  - skill-id-one
  - skill-id-two
  - skill-id-three

Wichtig: Alle Agenten erben automatisch die Standard-Skills (

meditate

heal

) aus dem

default_skills

-Feld der Registry. Diese NICHT im Frontmatter des Agenten aufführen, es sei denn, sie sind Kern der Methodik des Agenten (z.B. listet der Agent

mystic

meditate

auf, weil Meditationsbegleitung sein primaerer Zweck ist).

Erwartet: Die Skills-Liste enthaelt 3-15 Skill-IDs, die in

skills/_registry.yml

existieren.

Bei Fehler: Pruefen ob jede Skill-ID existiert:

grep "id: skill-name" skills/_registry.yml

. Alle entfernen, die nicht uebereinstimmen.

Schritt 5: Die Agentendatei schreiben

Vorlage kopieren und Frontmatter ausfuellen:

cp agents/_template.md agents/<agent-name>.md

Das YAML-Frontmatter ausfuellen:

---
name: agent-name
description: Ein bis zwei Saetze zur primaeren Faehigkeit und Domain
tools: [Read, Write, Edit, Bash, Grep, Glob]
model: sonnet
version: "1.0.0"
author: Philipp Thoss
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: [domain, specialty, relevant-keywords]
priority: normal
max_context_tokens: 200000
skills:
  - assigned-skill-one
  - assigned-skill-two
# Hinweis: Alle Agenten erben Standard-Skills (meditate, heal) aus der Registry.
# Diese nur hier aufführen, wenn sie Kern der Methodik dieses Agenten sind.
# mcp_servers: []  # Bei Bedarf auskommentieren und befuellen
---

Erwartet: YAML-Frontmatter wird fehlerfrei geparst. Alle Pflichtfelder (

name

description

tools

model

version

author

) vorhanden.

Bei Fehler: YAML-Syntax validieren. Haeufige Probleme: fehlende Anfuehrungszeichen um Versionsstrings, falsche Einrueckung, nicht geschlossene Klammern in Werkzeuglisten.

Schritt 6: Zweck und Faehigkeiten schreiben

Die Abschnittsplatzhalter der Vorlage ersetzen:

Zweck: Ein Absatz, der das spezifische Problem erklaert, das dieser Agent loest und den Mehrwert den er bietet. Konkret sein — Domain, Workflow und Ergebnis benennen.

Faehigkeiten: Aufzaehlungsliste mit fettgedruckten Vorsaetzen. Bei vielen Faehigkeiten nach Kategorie gruppieren:

## Capabilities

- **Primaere Faehigkeit**: Was der Agent am besten kann
- **Sekundaere Faehigkeit**: Zusaetzliche Funktionalitaet
- **Werkzeugintegration**: Wie er seine Werkzeuge nutzt

Verfuegbare Skills: Jeden zugewiesenen Skill mit einer kurzen Beschreibung auflisten. Bare Skill-IDs verwenden (die Slash-Command-Namen):

## Available Skills

- `skill-id` - Kurze Beschreibung was der Skill tut

Erwartet: Zweck ist spezifisch (nicht "hilft bei der Entwicklung"), Faehigkeiten sind konkret und pruefbar, Skills-Liste stimmt mit Frontmatter ueberein.

Bei Fehler: Falls der Zweck vage wirkt, beantworten: "Welche spezifische Aufgabe wuerde ein Benutzer diesen Agenten bitten zu erledigen?" Diese Antwort als Zweck verwenden.

Schritt 7: Verwendungsszenarien und Beispiele schreiben

2-3 Verwendungsszenarien bereitstellen, die zeigen, wie der Agent gestartet wird:

### Szenario 1: Primaerer Anwendungsfall
Kurze Beschreibung des Hauptszenarios.

> "Verwende den agent-name-Agenten fuer [spezifische Aufgabe]."

### Szenario 2: Alternativer Anwendungsfall
Beschreibung eines anderen gaengigen Anwendungsfalls.

> "Starte den agent-name fuer [andere Aufgabe]."

1-2 konkrete Beispiele hinzufuegen, die eine Benutzeranfrage und das erwartete Agentenverhalten zeigen:

### Beispiel 1: Grundlegende Nutzung
**Benutzer**: [Spezifische Anfrage]
**Agent**: [Erwartetes Antwortmuster und durchgefuehrte Aktionen]

Erwartet: Szenarien sind realistisch, Beispiele zeigen echten Mehrwert, Aufrufmuster entsprechen Claude-Code-Konventionen.

Bei Fehler: Beispiele gedanklich testen — waere der Agent mit seinen zugewiesenen Werkzeugen und Skills tatsaechlich in der Lage, die Anfrage zu erfuellen?

Schritt 8: Einschraenkungen und Siehe-auch schreiben

Einschraenkungen: 3-5 ehrliche Beschraenkungen. Was der Agent nicht kann, wofuer er nicht verwendet werden sollte, oder wo er schlechte Ergebnisse liefern koennte:

## Limitations

- Kann keinen Code in Sprache X ausfuehren (keine Laufzeitumgebung verfuegbar)
- Nicht geeignet fuer Aufgaben die Y erfordern — stattdessen Agent Z verwenden
- Benoetigt MCP-Server ABC zum Laufen fuer volle Funktionalitaet

Siehe auch: Ergnzende Agenten, relevante Leitfaeden und verwandte Teams querverweisen:

## See Also

- [complementary-agent](complementary-agent.md) - behandelt die X-Seite dieses Workflows
- [relevant-guide](../guides/guide-name.md) - Hintergrundwissen fuer diese Domain
- [relevant-team](../teams/team-name.md) - Team das diesen Agenten einschliesst

Erwartet: Einschraenkungen sind ehrlich und spezifisch. See-Also-Referenzen zeigen auf existierende Dateien.

Bei Fehler: Pruefen ob referenzierte Dateien existieren:

ls agents/complementary-agent.md

Schritt 9: Zur Registry hinzufuegen

agents/_registry.yml

bearbeiten und den neuen Agenteneintrag in alphabetischer Position hinzufuegen:

  - id: agent-name
    path: agents/agent-name.md
    description: Dieselbe einzeilige Beschreibung wie im Frontmatter
    tags: [domain, specialty]
    priority: normal
    tools: [Read, Write, Edit, Bash, Grep, Glob]
    skills:
      - skill-id-one
      - skill-id-two

Den

total_agents

-Zaehler am Anfang der Datei hochzaehlen.

Erwartet: Registry-Eintrag stimmt mit Agentendatei-Frontmatter ueberein.

total_agents

entspricht der tatsaechlichen Anzahl der Agenteneintraege.

Bei Fehler: Eintraege zaehlen mit

grep -c "^  - id:" agents/_registry.yml

und pruefen ob es

total_agents

entspricht.

Schritt 10: Erkennbarkeit pruefen

Claude Code entdeckt Agenten aus dem Verzeichnis

.claude/agents/

. In diesem Repository ist dieses Verzeichnis ein Symlink zu

agents/

# Pruefen ob der Symlink existiert und aufloest
ls -la .claude/agents/
readlink -f .claude/agents/<agent-name>.md

Falls der Symlink

.claude/agents/

intakt ist, sind keine weiteren Massnahmen erforderlich — die neue Agentendatei ist automatisch erkennbar.

README-Automatisierung ausfuehren, um das Agenten-README zu aktualisieren:

npm run update-readmes

Erwartet:

.claude/agents/<agent-name>.md

loest sich zur neuen Agentendatei auf.

agents/README.md

beinhaltet den neuen Agenten.

Bei Fehler: Falls der Symlink defekt ist, neu erstellen:

ln -sf ../agents .claude/agents

. Falls

npm run update-readmes

fehlschlaegt, pruefen ob

scripts/generate-readmes.js

existiert und

js-yaml

installiert ist.

Schritt 11: Uebersetzungen anlegen

Erforderlich fuer alle Agenten. Dieser Schritt gilt sowohl fuer menschliche Autoren als auch fuer KI-Agenten, die dieser Vorgehensweise folgen. Nicht ueberspringen — fehlende Uebersetzungen sammeln sich zu einem veralteten Backlog an.

Unmittelbar nach dem Committen des neuen Agenten Uebersetzungsdateien fuer alle 4 unterstuetzten Locales anlegen:

for locale in de zh-CN ja es; do
  npm run translate:scaffold -- agents <agent-name> "$locale"
done

Anschliessend die angelegte Prosa in jeder Datei uebersetzen (Code-Bloecke und IDs bleiben auf Englisch). Abschliessend die Statusdateien neu generieren:

npm run translation:status

Erwartet: 4 Dateien unter

i18n/{de,zh-CN,ja,es}/agents/<agent-name>.md

erstellt, alle mit

source_commit

, der dem aktuellen HEAD entspricht.

npm run validate:translations

zeigt 0 Stale-Warnungen fuer den neuen Agenten.

Bei Fehler: Falls das Scaffolding fehlschlaegt, pruefen ob der Agent in

agents/_registry.yml

existiert. Falls sich die Statusdateien nicht aktualisieren,

npm run translation:status

explizit ausfuehren — es wird nicht automatisch von CI ausgeloest.

Validierung

Agentendatei existiert unter
```
agents/<agent-name>.md
```
YAML-Frontmatter wird fehlerfrei geparst
Alle Pflichtfelder vorhanden:
```
name
```
,
```
description
```
,
```
tools
```
,
```
model
```
,
```
version
```
,
```
author
```
```
name
```
-Feld stimmt mit dem Dateinamen (ohne
```
.md
```
) ueberein
Alle Abschnitte vorhanden: Purpose, Capabilities, Available Skills, Usage Scenarios, Examples, Limitations, See Also
Skills im Frontmatter existieren in
```
skills/_registry.yml
```
Standard-Skills (
```
meditate
```
,
```
heal
```
) sind NICHT aufgefuehrt, es sei denn sie sind Kern der Agentenmethodik
Werkzeugliste folgt dem Prinzip der minimalen Berechtigungen
Agent ist in
```
agents/_registry.yml
```
mit korrektem Pfad und passenden Metadaten aufgefuehrt
```
total_agents
```
-Zaehler in der Registry ist aktualisiert
```
.claude/agents/
```
-Symlink loest sich zur neuen Agentendatei auf
Keine wesentliche Ueberschneidung mit bestehenden Agenten

Haeufige Stolperfallen

Werkzeug-Ueberversorgung:
```
Bash
```
,
```
Write
```
oder
```
WebFetch
```
einbeziehen, wenn der Agent nur lesen und analysieren muss. Dies verletzt das Prinzip der minimalen Berechtigungen und kann zu unbeabsichtigten Nebeneffekten fuehren.
Fehlende oder falsche Skill-Zuweisungen: Skill-IDs auflisten, die nicht in der Registry existieren, oder vergessen Skills zuzuweisen. Immer jede Skill-ID mit
```
grep "id: skill-name" skills/_registry.yml
```
pruefen.
Standard-Skills unnoetig auflisten:
```
meditate
```
oder
```
heal
```
zum Agenten-Frontmatter hinzufuegen, obwohl sie bereits aus der Registry geerbt werden. Nur auflisten wenn sie Kern der Agentenmethodik sind.
Umfangs-Ueberschneidung mit bestehenden Agenten: Einen neuen Agenten erstellen, der Funktionalitaet dupliziert, die bereits von einem der 53 bestehenden Agenten abgedeckt wird. Immer zuerst die Registry durchsuchen und erwaegen einen bestehenden Agenten zu erweitern.
Vager Zweck und vage Faehigkeiten: "Hilft bei der Entwicklung" schreiben statt "Geruest fuer R-Pakete mit vollstaendiger Struktur, Dokumentation und CI/CD-Konfiguration". Spezifitaet macht einen Agenten nuetzlich und auffindbar.