description: Validiert Agenten-Dateien, YAML-Frontmatter (inkl. color-Attribut) und Best Practices category: develop allowed-tools:

• Read
• Glob
• Grep
• Bash

Agent Validation Tool

Dieser Command validiert Claude Code Agenten auf:

• YAML-Frontmatter Struktur (inkl. color-Attribut)
• Markdown-Syntax
• Agent-spezifische Best Practices
• Vollständigkeit der Dokumentation

Usage

# Spezifischen Agenten prüfen
/develop:check-agents claude/agents/code-reviewer.md

# Oder ohne Pfad für interaktive Auswahl
/develop:check-agents

Validierungs-Checks

1. YAML-Frontmatter

Required:

• name (String, lowercase mit Bindestrichen, z.B. "code-reviewer")
• description (String, 1-200 Zeichen)
• color (String, eine der erlaubten Farben)

Optional:

• category (String, z.B. "quality-security", "specialized-domains")
• model (String: "sonnet", "opus", "haiku")
• tools (Array von Tool-Namen oder Komma-separierter String)
• allowed-tools (Array von Tool-Namen)

Format:

---
name: code-reviewer
description: Experte für Code-Reviews mit Fokus auf Qualität und Sicherheit
category: quality-security
model: sonnet
color: blue
tools: Read, Write, Grep
---

2. Color-Attribut Validierung

Erlaubte Farben:

• blue - Standard für Code-/Entwicklungs-Agenten
• green - Für Testing-/Validierungs-Agenten
• red - Für Security-/Critical-Agenten
• yellow - Für Dokumentations-Agenten
• purple - Für Research-/Analyse-Agenten
• orange - Für Build-/Deployment-Agenten
• cyan - Für Data-/Database-Agenten
• magenta - Für UI/UX-Agenten

Validation:

• ✅ Color-Attribut muss vorhanden sein
• ✅ Color muss eine der erlaubten Farben sein
• ✅ Color sollte zur Kategorie/Funktion passen

Empfehlungen:

# Gut ✅
name: code-reviewer
category: quality-security
color: blue

# Gut ✅
name: test-automator
category: testing
color: green

# Fehlt ❌
name: markdown-formatter
category: specialized-domains
# KEIN color-Attribut!

# Falsche Farbe ❌
name: security-auditor
color: pink  # Nicht erlaubt

3. Markdown-Struktur

• Muss mit Frontmatter beginnen
• Mindestens eine H1-Überschrift (# Agent Name)
• Valides CommonMark-Format
• Klare Abschnitte (Rolle, Aktivierung, Prozess, etc.)

Empfohlene Struktur:

# Agent Name

[Kurze Beschreibung]

## Rolle / Core Expertise

[Was der Agent kann]

## Aktivierung / Vorgehen

[Wann und wie der Agent verwendet wird]

## Prozess / Workflow

[Schritt-für-Schritt Ablauf]

## Bereitstellung / Output

[Was der Agent liefert]

4. Agent-spezifische Best Practices

Name:

• ✅ Lowercase mit Bindestrichen: code-reviewer
• ❌ CamelCase oder Unterstriche: CodeReviewer, code_reviewer
• ✅ Beschreibend und prägnant
• ✅ Stimmt mit Dateinamen überein (ohne .md)

Description:

• Kurz und prägnant (1-200 Zeichen)
• Beschreibt WAS der Agent tut
• Optional: WANN der Agent verwendet werden soll
• Optional: Proaktiv-Hinweis ("MUST BE USED when...", "Use PROACTIVELY...")
• Sprache: Deutsch (technische Begriffe auf Englisch erlaubt)

Dokumentation (Markdown-Body):

• Primär auf Deutsch verfasst
• Technische Begriffe (z.B. "Code-Review", "Testing") können auf Englisch bleiben
• Fachbegriffe (z.B. "Progressive Disclosure") auf Englisch erlaubt
• Konsistente Sprache innerhalb eines Agenten

Category (optional, aber empfohlen):

• Gruppiert verwandte Agenten
• Beispiele: quality-security, specialized-domains, skill-builder, development, testing

Model (optional):

• sonnet - Standard (balanced)
• opus - Komplexe Aufgaben
• haiku - Schnelle, einfache Aufgaben

Validierungs-Workflow

Wenn du diesen Command ausführst, solltest du:

1. Agenten-Pfad ermitteln:

   • Falls kein Pfad angegeben: Alle .md-Dateien in claude/agents/ listen (rekursiv)
   • User wählt Agenten aus oder du verarbeitest alle

2. Datei einlesen:

   • Read-Tool verwenden
   • Prüfen ob Datei existiert

3. YAML-Frontmatter parsen:

   • Ersten Block zwischen --- extrahieren
   • Required-Felder prüfen: name, description, color
   • Optional-Felder validieren: category, model, tools
   • Format-Validierung (keine Syntax-Fehler)

4. Color-Attribut Check:

   • ❌ Fehlt color-Attribut komplett?
   • ❌ Ist color nicht in erlaubten Farben?
   • ⚠️ Passt color zur Kategorie/Funktion?

5. Markdown validieren:

   • Mindestens eine H1-Überschrift vorhanden
   • Name in H1 stimmt mit name in YAML überein (empfohlen)
   • Grundlegende CommonMark-Struktur

6. Name validieren:

   • Lowercase mit Bindestrichen
   • Stimmt mit Dateinamen überein
   • Format: [a-z][a-z0-9-]*

7. Report ausgeben

   Erfolgreicher Agent:

   ## Validation Report: code-reviewer
   
   ✅ YAML-Frontmatter: Valid
   ✅ Color-Attribut: blue (valid ✓)
   ✅ Markdown-Struktur: Valid
   ✅ Name Convention: Valid
   ✅ Best Practices: Compliant
   
   ### Details:
   - Name: code-reviewer (matches filename ✓)
   - Description: "Experte für Code-Reviews..." (91 chars ✓)
   - Category: quality-security ✓
   - Model: sonnet ✓
   - Color: blue (appropriate for code-review ✓)
   
   ✨ Agent is fully compliant!
   

   Agent mit fehlendem Color:

   ## Validation Report: markdown-syntax-formatter
   
   ✅ YAML-Frontmatter: Valid (except color)
   ❌ Color-Attribut: MISSING
   ✅ Markdown-Struktur: Valid
   ✅ Name Convention: Valid
   ⚠️  Best Practices: Partially compliant
   
   ### Issues to fix:
   1. ❌ REQUIRED: Add 'color' field to YAML frontmatter
      Recommended: color: yellow (documentation/formatting agent)
   
   ### Recommended fix:
   ```yaml
   ---
   name: markdown-syntax-formatter
   category: specialized-domains
   description: Konvertiert Text mit visueller Formatierung...
   color: yellow  # ADD THIS LINE
   ---
   

   Available colors

   • blue: Code/Development agents
   • green: Testing/Validation agents
   • red: Security/Critical agents
   • yellow: Documentation agents ← RECOMMENDED
   • purple: Research/Analysis agents
   • orange: Build/Deployment agents
   • cyan: Data/Database agents
   • magenta: UI/UX agents

   Agent mit ungültiger Color:

   ## Validation Report: example-agent
   
   ✅ YAML-Frontmatter: Valid (except color)
   ❌ Color-Attribut: INVALID ("pink" not allowed)
   ✅ Markdown-Struktur: Valid
   ✅ Name Convention: Valid
   
   ### Issues to fix:
   1. ❌ Color "pink" is not in allowed colors list
      Change to one of: blue, green, red, yellow, purple, orange, cyan, magenta
   
   ### Recommended fix:
   Choose appropriate color based on agent function:
   - If code-related → blue
   - If testing-related → green
   - If security-related → red
   - If documentation-related → yellow
   - If research-related → purple
   

8. Bulk-Validierung (alle Agenten):

   ## Bulk Validation Report: claude/agents/
   
   Found 5 agent files:
   
   ✅ code-reviewer.md - Fully compliant
   ❌ markdown-syntax-formatter.md - Missing color
   ❌ skill-documenter-agent.md - Missing color
   ❌ skill-elicitation-agent.md - Missing color
   ❌ skill-generator-agent.md - Missing color
   
   ### Summary:
   - Total agents: 5
   - Compliant: 1 (20%)
   - Missing color: 4 (80%)
   - Invalid color: 0 (0%)
   - Other issues: 0 (0%)
   
   ### Agents needing color attribute:
   1. markdown-syntax-formatter.md → Recommended: yellow
   2. skill-documenter-agent.md → Recommended: yellow
   3. skill-elicitation-agent.md → Recommended: purple
   4. skill-generator-agent.md → Recommended: blue
   
   ### Quick fix script:
   Would you like me to add the recommended colors to all agents?
   

Error Handling

• Datei nicht gefunden: Klare Fehlermeldung mit Pfad
• YAML-Parse-Fehler: Zeige Zeile und Fehler
• Fehlende Required-Felder: Liste alle fehlenden Felder (inkl. color!)
• Ungültige Color: Zeige erlaubte Farben + Empfehlung

Auto-Fix Option

Nach der Validierung kannst du optional anbieten:

🔧 Auto-Fix verfügbar!

Soll ich die fehlenden color-Attribute automatisch hinzufügen?
[Ja] Füge empfohlene Farben hinzu
[Nein] Nur Report anzeigen
[Manuell] Zeige mir was zu tun ist

Falls "Ja":

• Analysiere Agent-Funktion aus name und description
• Wähle passende Farbe
• Füge color: [farbe] zum YAML-Frontmatter hinzu
• Zeige Diff vor dem Schreiben

Integration mit anderen Commands

Dieser Command ist nützlich:

• Vor dem Commit: Agenten validieren bevor sie commited werden
• Nach Änderungen: Sicherstellen dass alle Agenten compliant sind
• Neue Agenten: Initiales Setup überprüfen
• Bulk-Check: Alle Agenten auf einmal prüfen

Beispiele

Einzelner Agent mit Color:

/develop:check-agents claude/agents/code-reviewer.md
→ ✅ Fully compliant (color: blue)

Einzelner Agent ohne Color:

/develop:check-agents claude/agents/markdown-syntax-formatter.md
→ ❌ Missing color attribute
→ 💡 Recommended: yellow (documentation agent)

Alle Agenten prüfen:

/develop:check-agents
→ Found 5 agents, 4 missing color
→ [Bulk Report anzeigen]

Mit Auto-Fix:

/develop:check-agents --fix
→ Fixed 4 agents, added color attributes
→ [Show changes]

Color-Kategorie Mapping

Zur Orientierung für Auto-Fix oder manuelle Zuweisung:

Keywords für Auto-Detection:

• Blue: "code", "review", "developer", "engineer", "refactor"
• Green: "test", "validate", "check", "verify", "qa"
• Red: "security", "audit", "vulnerability", "pentest"
• Yellow: "document", "write", "markdown", "format", "guide"
• Purple: "research", "analyze", "investigate", "synthesize"
• Orange: "build", "deploy", "ci", "cd", "release"
• Cyan: "data", "database", "query", "etl", "pipeline"
• Magenta: "ui", "ux", "design", "interface", "accessibility"

Notes

• Dieser Command sollte selbst Best Practices folgen ✨
• Color-Attribut ist ab sofort REQUIRED für alle Agenten
• Auto-Fix sollte intelligent Farben vorschlagen basierend auf Agent-Funktion
• Bei Unsicherheit: Nutzer fragen welche Farbe gewünscht ist