az-agent-defaults/README.md

az-agent-defaults — Company-Default-Set für Agenten-Artefakte

Dieses Repo ist die eine Wahrheitsquelle für die Standard-Artefakte, die jede Agenten-Workstation der AZ-Gruppe gespiegelt bekommt. Es ist ein reines Content-Repo: hier leben nur die Inhalte — die Technik, die sie ausliefert und absichert, gehört in das Fleet-Repo az-fleet (siehe Trennung Content / Mechanismus).

Das Repo hervorgegangen aus az-agent-skills und löst es ab: der alte Name würde lügen, seit neben Skills auch Commands, Agenten-Definitionen und MCP-Server-Anbindungen dazugekommen sind.

---

Wohin gehört mein Beitrag?

Ich möchte beitragen …	Verzeichnis	Form
einen Skill (Verhaltens-Anweisung, die der Agent bei Bedarf lädt)	skills/<name>/	Ordner mit SKILL.md
einen Command (/slash-Befehl, wiederverwendbarer Prompt)	commands/<name>.md	Markdown-Datei mit Frontmatter
einen Agenten (spezialisiertes Profil als Primäragent oder Subagent)	agents/<name>.md	Markdown-Datei mit Frontmatter
einen MCP-Server (Werkzeug-Anbindung)	mcp/<name>.yaml	Konfigurations-Fragment

Kurzform zum Einsortieren:

• Verhalten beibringen („mach X, wenn Y") → skills/
• Wiederkehrenden Prompt als Tastendruck → commands/
• Eigenes Agenten-Profil / Prüf-Subagenten → agents/
• Werkzeug anbinden (API, Datenquelle) → mcp/

Alle vier Verzeichnisse werden von der Delivery-Rolle des Fleet-Repos gelesen — und nur diese vier. Alles andere im Repo (z. B. tests/fixtures/, diese README, die Spec) wird nie ausgeliefert.

---

Guard-Regeln je Artefakt-Typ

Die Delivery-Rolle in az-fleet führt vor jedem Rollout einen deterministischen Pre-Flight-Guard aus: Struktur-, Frontmatter- und Platzhalter-Checks je Typ. Ein ungültiges Artefakt bricht den Run kontrolliert ab — kaputte Inhalte erreichen nie eine Maschine. Die Regeln unten beschreiben, was der Guard mindestens prüft; die Implementierung lebt in az-fleet, nicht hier.

skills/ — Skills

Struktur: ein Ordner pro Skill, darin genau eine SKILL.md.

skills/
└── mein-skill/
    └── SKILL.md

Anforderungen:

• Ordnername = Skill-Name (kein Leerzeichen, keine Umlaute; kebab-case).
• SKILL.md beginnt mit einem YAML-Frontmatter-Öffner (Delimited by ---).
• Frontmatter enthält Pflichtfelder name und description.
  • name muss zum Ordnernamen passen.
  • description ist ein Satz, der sagt, wann der Skill greift.
• Darunter: Anweisungen als normales Markdown.

Minimalbeispiel:

---
name: mein-skill
description: Prüft Zugferd-Rechnungen auf formal korrektes XML, wenn der Nutzer eine XRechnung validieren will.
---

# Zugferd-Validierung

Prüfe die übergebene Datei gegen das CIUS-XRechnung-Schema …

Typische Fehler, die der Guard abbricht: fehlender Ordner, fehlende SKILL.md, fehlendes/leeres Frontmatter, name ≠ Ordnername, fehlende description.

commands/ — Commands (/slash-Befehle)

Struktur: eine Markdown-Datei pro Command, direkt in commands/.

commands/
└── ticket-abarbeiten.md

Anforderungen:

• Dateiname ohne .md = Command-Name → in der Sitzung als /ticket-abarbeiten verfügbar.
• Frontmatter mit:
  • description (Pflicht) — erscheint in der Command-Übersicht;
  • agent (optional) — Agent, der den Command ausführt;
  • model (optional) — Modell für die Ausführung.
• Body = Template. Argument-Platzhalter sind erlaubt und erwünscht:
  • $ARGUMENTS — alles, was der Nutzer nach dem Command tippt;
  • $1 … $n — positionelle Argumente.

Minimalbeispiel:

---
description: Arbeitet das genannte beads-Ticket ab (claimen, umsetzen, schließen).
agent: build
---

Arbeite das Ticket $ARGUMENTS ab: zeige es mir, claime es, setze es um und
schließ es nach meiner Freigabe.

Typische Fehler: fehlendes Frontmatter, fehlende description, Command-Name mit Leerzeichen/Umlauten (die später zum /slash-Namen wird).

agents/ — Agenten-Definitionen

Struktur: eine Markdown-Datei pro Agent, direkt in agents/. Dateiname = Agentenname.

Anforderungen:

• Frontmatter mit:
  • description (Pflicht) — sagt, wofür der Agent da ist;
  • mode (Pflicht) — primary (per Agentenwechsel wählbar) oder subagent (per @mention und automatisch über das Task-Tool startbar);
  • model, temperature (optional);
  • Permission-/Tool-Profil (optional, aber für Subagents empfohlen) — z. B. ein Read-only-Prüfer ohne Edit/Bash.
• Body = Systemprompt des Agenten.

Harte Sicherheitsregeln (Guard prüft mit):

1. Subagent-Fähigkeit bleibt erhalten: keine Definition darf das Task-Tool bzw. die Delegation an Subagents so einschränken, dass Subagents nicht mehr startbar wären. Spezialisierung ja — die Fähigkeit von Agenten, selbst zu delegieren und zu parallelisieren, wird nie verbaut.
2. Niemals Rechte ausweiten: Permission-Profile dürfen innerhalb des verwalteten Regelwerks (Managed-Layer) nur einschränken, nie erlauben, was der Managed-Layer verweigert. Provider-Lock und Permission-Regelwerk gelten unabhängig vom aktiven Agenten weiter.

Minimalbeispiel (Read-only-Subagent):

---
description: Prüft Ergebnisse gegen Abnahme-Kriterien, ohne selbst zu ändern.
mode: subagent
temperature: 0.1
tools:
  - read
  - grep
  - glob
---

Du bist ein Read-only-Prüfer. Gleiche das vorgelegte Ergebnis gegen die
Abnahme-Kriterien ab und berichte nur — du editierst und schreibst nichts.

Typische Fehler: fehlende mode, mode mit ungültigem Wert, Frontmatter ohne description.

mcp/ — MCP-Server-Fragmente

Struktur: eine YAML-Datei pro Server: mcp/<server-name>.yaml. Jede Datei ist ein Fragment für den mcp-Konfigurationsschlüssel — der Server-Name steht als Schlüssel, darunter die Definition. Die Fragmente werden auf dem Controller in die verwaltete Konfiguration (Managed-Layer) gemerged — MCPs sind Werkzeuge und damit sicherheitsrelevant, sie gehören in den admin-kontrollierten Layer, nicht auf die nutzerbeschreibbare Ebene.

Anforderungen:

• Standard ist remote/streamable mit OAuth: type: remote plus url; die Anmeldung läuft zur Laufzeit einmalig pro Nutzer über dessen Microsoft-Konto — identitätsgebunden. Ein OAuth-Server braucht daher kein Credential-Feld im Fragment.
• enabled (optional) — Standard ist an.
• local-Server (command/env) nur als dokumentierte Ausnahme.
• Secrets niemals im Repo — ohne Ausnahme. Wo ein statischer Key nötig ist (Nicht-OAuth-Ausnahme), steht im Fragment nur ein Platzhalter der Form ${VAULT:<key-name>}; der echte Key liegt im Vault des Fleet-Repos und wird erst beim Merge auf dem Controller substituiert. Im Repo bleibt nie ein Secret.
  • Vault-Key-Namensschema: <server-name>-<verwendungszweck> in kebab-case — z. B. ${VAULT:az-zoll-service-api-key} für den API-Key des Servers az-zoll-service. Ein Key pro Credential, im Vault der IT eindeutig zuordenbar.

Minimalbeispiel (OAuth-Standardfall):

# mcp/zugferd-service.yaml
zugferd-service:
  type: remote
  url: https://mcp.example.az.local/zugferd
  enabled: true

Beispiel (dokumentierte Key-Ausnahme):

# mcp/az-zoll-service.yaml — kein OAuth verfügbar: statischer Key aus dem Vault
az-zoll-service:
  type: remote
  url: https://mcp.example.az.local/zoll
  headers:
    Authorization: Bearer ${VAULT:az-zoll-service-api-key}
  enabled: true

Typische Fehler: Server-Name fehlt (Datei ist keine Fragment-Struktur), fehlende url, type fehlt bei remote, ein Secret im Klartext (Guard bricht ab — auch in Kommentaren), Platzhalter in anderer Syntax als ${VAULT:…}.

---

Agenten-Prompt-Standard

Die Guard-Regeln oben sagen deterministisch, was ein Artefakt gültig macht. Dieser Abschnitt sagt, was ein Agenten-Prompt gut macht — und ist bewusst eine weiche Regel: Der Fleet-Guard erzwingt sie nicht. Geprüft wird vom Prüfer-Agenten az-pruefer (LLM-Prüfung) — ein Verstoß bricht keinen Rollout ab, wird aber im Prüfbericht als Mangel benannt und muss behoben oder ausdrücklich begründet werden.

Prompt-Skelett

Jeder Agenten-Body folgt diesem Skelett (Reihenfolge einhalten; Überschriften dürfen sinngemäß abweichen):

<Rollen-Eröffnung: wer du bist, wer dich ruft>

## Arbeitsweise
1. **<Schritt>** — <Anweisung mit erkennbarem Abschlusskriterium>.

## Ausgabeformat
<Output-Vertrag — für Subagents Pflicht, siehe unten>

## Grenzen
- <Was der Agent nie tut; Auth, Fleet-Verwaltung, Eskalation>

• Arbeitsweise: nummerierte Schritte, jeder mit erkennbarem Abschlusskriterium. Gibt es einen gepflegten Skill fürs Thema — auch aus external/, deren Skills via az-fleet auf die Nutzerebene ausgerollt werden —, ist Skill-Load der erste Schritt („dünne Agent-Shell über gepflegtem Skill", Muster: az-office + officecli). Inline-Wissen, das der Skill bereits trägt, bleibt draußen.
• Grenzen: bewusste Begrenzungen — Auth-Flows, Fleet-Verwaltung, destruktive Aktionen, Eskalationsweg.
• Tool-/MCP-Freigabe: Schränkt ein Agent Tools ein (tools: bzw. permission:), muss er jedes benötigte MCP-Tool explizit freigeben — MCP-Tools heißen <ServerName>_<ToolName> (z. B. Websearch_web_search_exa für den Exa-Server Websearch aus mcp/). Ohne Profil gelten die Defaults des Harness.

Trigger-Description

Die Frontmatter-description entscheidet, ob Orchestrator oder Nutzer den Agenten auswählen. Deshalb:

• Subagents (vom Orchestrator über die Routing-Tabelle gewählt): In den ersten 80 Zeichen stehen konkrete Beispielfragen/-aufträge, so wie Nutzer sie tatsächlich stellen — z. B. „Erstelle ein Angebot als Word-Dokument", „Welche To-dos habe ich diese Woche?". Danach Kurzform der Fähigkeiten; Rolle/Zugehörigkeit ans Ende. Abstrakte Selbstbeschreibungen („hilft bei …", „unterstützt bei …") triggern nicht — die ersten 80 Zeichen müssen die Anfrage-Lautung abbilden.
• Primary-Agenten (vom Nutzer aus einer Liste gewählt): In den ersten 80 Zeichen steht der Missionssatz — ein prägnanter Satz, wofür der Agent der Standard-Anlaufpunkt ist. Danach Trigger-Beispiele und Fähigkeiten.

Output-Vertrag (Subagent-Pflicht)

Jeder Subagent definiert eine Sektion ## Ausgabeformat mit mindestens:

• Ergebnis — Antwort bzw. Arbeitsergebnis zuerst;
• Belege — je Behauptung/Aktion eine Fundstelle: URL, Datei:Zeile oder Beleg-ID;
• Offene Punkte — was unklar, ungeprüft oder Annahme blieb.

Der Vertrag ist die Verifikations-Grundlage des Orchestrators: Fehlen Belege, lässt er nachbessern. Failure-Regel: eine Behauptung ohne Beleg ist ein gescheiterter Auftrag — keine abgeschlossene Arbeit.

Sprachregel

In jedem Agenten steht die Regel: „Antworte in der Sprache der Anfrage." (der Orchestrator nutzt die gleichbedeutende Variante „Antworte in der Sprache der Nutzeranfrage.") Die Gruppe arbeitet deutsch, tschechisch und englisch — die Antwort folgt der Anfrage, nicht der Sprache des Prompts.

Größen-Grenze

Agenten-Prompts bleiben unter 10.000 Zeichen. Wird ein Prompt länger, wandert Inhalt in einen Skill, den der Agent als ersten Schritt lädt (Progressive Disclosure). Dünner Prompt über gepflegtem Skill schlägt fetten Inline-Prompt.

---

Trennung Content / Mechanismus

Zuständigkeit	Repo
Inhalte (Skills, Commands, Agents, MCP-Fragmente)	az-agent-defaults (dieses Repo)
Mechanismus (Guard-Engine, Auslieferung/Spiegel, Drift-Reparatur, Vault-Substitution)	az-fleet

Konsequenzen für Contributors:

• Dieses Repo enthält keine Auslieferungs-Logik, kein Playbook, kein Secret.
• Skills, Commands und Agenten-Definitionen werden als exakter Nutzerebene-Spiegel ausgeliefert (inklusive Entfernen gelöschter Artefakte).
• MCP-Fragmente werden auf dem Controller in den Managed-Layer gemerged und unterliegen dessen Admin-ACL.
• Der Stand dieses Repos wird über einen Repo-Ref gepinnt (Default: main). Jeder Rollout ist damit deterministisch reproduzierbar; die Pin-Logik lebt in az-fleet.

tests/fixtures/ — Testgegenstände, nie ausgeliefert

Guard-Tests brauchen gültige und ungültige Artefakt-Exemplare als Testgegenstände. Diese Fixtures leben unter tests/fixtures/ — denn die Delivery-Rolle liest nur die vier Typ-Verzeichnisse, also kann unter tests/fixtures/ nichts „mitschwimmen" und versehentlich ausgeliefert werden. (Sonntags-Entscheidung: bewusst kein eigener Auslieferungs-Ausschluss-Mechanismus, sondern Trennung durch das Lese-Muster der Delivery-Rolle.)

Konvention: je Artefakt-Typ ein Unterordner, darin valid/- und invalid/-Exemplare, an denen der Guard durch- bzw. abbricht.

tests/fixtures/
├── skills/valid/…   skills/invalid/…
├── commands/valid/… commands/invalid/…
├── agents/valid/…   agents/invalid/…   agents/demo/…
└── mcp/valid/…      mcp/invalid/…

Regel: alles unter tests/fixtures/ ist Testgegenstand und wird nie ausgeliefert — nichts daraus in die Typ-Verzeichnisse schieben; umgekehrt sind echte Artefakte dort fehl am Platz.

Die Exemplare unter agents/demo/ bestehen den Guard, verstoßen aber gegen den (weichen) Agenten-Prompt-Standard — sie sind Prüfgut für az-pruefer, nicht für den Fleet-Guard.

---

Beitrags-Kurzanleitung

1. Richtiges Verzeichnis anhand der Tabelle oben wählen.
2. Artefakt gemäß Guard-Regeln des Typs anlegen (Minimalbeispiel als Vorlage) — bei Agenten zusätzlich: Agenten-Prompt-Standard.
3. Prüfen: erfüllt das Artefakt alle Pflichtpunkte der Checkliste seines Typs? Wenn unsicher — die Checklisten sind vollständig; es braucht kein Architektur-Wissen.
4. Commit/PR wie gewohnt. Der Guard läuft als Pre-Flight beim nächsten Rollout in az-fleet; erst nach Rollout und App-Neustart ist das Artefakt auf den Workstations.