semantic-persona-routing · diff

v1.0.0 to v1.1.0

64 added, 3 removed. Audit A to A.

---

name: semantic-persona-routing

- version: 1.0.0

+ version: 1.1.0

type: skill

author: Lukas Geiger + OpenAI

created: 2026-07-28

- updated: 2026-07-28

+ updated: 2026-09-03

description: >

Erstellt und verwendet einen anbieterneutralen semantischen Routing-Graphen

aus Personas, koordinierenden Rollen, Experten und aktiven Skill-Endpunkten.

Verwenden, wenn ein LLM eine Anfrage von einer Leitrolle über einen Experten

zu einem Skill routen, aus einem vorhandenen Agentensystem einen portablen

Persona-Router extrahieren, eine semantische Domänenkarte mit einer

lexikalischen Skill-Registry kombinieren oder fehlende Verbindungen zwischen

Rolle und Skill sichtbar machen soll, statt still auf einen Ersatz

zurückzufallen. Auslöser sind unter anderem semantisches Persona-Routing,

Persona-Umbrella, Rollen-Router, Boss-Agent-Experten-Skill-Routing,

Agentenrollen-Export oder die Wiederverwendung von Personas über mehrere

LLM-Anbieter hinweg.

standalone: true

anthropic_compatible: true

bach_compatible: true

bach_origin: false

category: infrastructure

- tags: [persona, semantic-routing, agents, experts, skills, umbrella, provider-neutral]

+ tags: [persona, persona-authoring, semantic-routing, agents, experts, skills, umbrella, provider-neutral]

language: de

status: active

visibility: public

dependencies:

tools: []

services: []

protocols: []

python: []

provenance:

origin: "custom"

origin_path: null

origin_version: null

origin_repo: "github.com/ellmos-ai/skills"

last_sync_from_origin: null

last_sync_to_origin: null

local_changes_since_sync: false

---

# Semantisches Persona-Routing

Route zuerst nach Fähigkeit und wende Persönlichkeit danach an. Erstelle eine

portable Karte, die semantische Rollenwahl, deterministische Endpunktsuche und

anbieterspezifisches Laden voneinander trennt.

## Routing-Modell

```text

Anfrage

-> semantische Domäne oder koordinierende Rolle

-> Expertenfähigkeit

-> ausdrücklich angegebener oder live aufgelöster Skill-Endpunkt

-> optionales Persona-Overlay

-> Anbieteradapter lädt und führt aus

```

Eine Persona steuert Kommunikationsstil, Prioritäten und Interaktionsmuster. Sie

verleiht keine Werkzeuge, Berechtigungen oder fachlichen Fähigkeiten. Eine Rolle

koordiniert, ein Experte grenzt die Domäne ein, und ein Skill ist der

ausführbare Endpunkt.

## Routing-Karte erstellen

Nutze ausdrückliche Metadaten als maßgebliche Quelle und lexikalische Ähnlichkeit

nur zur Kandidatensuche:

```bash

python scripts/build_routing_map.py \

--roles-dir path/to/roles \

--personas-dir path/to/personas \

--skills-dir path/to/skills \

--out routing-map.json

```

Der Builder versteht verbreitete `SKILL.md`-Felder wie `type`,

`orchestrates.experts`, `parent_agents`, `skills`, Beschreibungen und Herkunft.

Er erzeugt eine Laufzeitkarte, ohne dass das Quellsystem installiert sein muss.

Lies [routing-map-schema.md](references/routing-map-schema.md), bevor du das

Format erweiterst.

Jede exportierte Skill-ID ist eindeutig. Deklarieren mehrere Quelldateien dieselbe

stabile ID, wählt der Builder deterministisch den lexikografisch ersten relativen

Quellpfad und vermerkt ein `duplicate-skill-id`-Issue; er gibt nie zwei

Skill-Einträge mit derselben ID aus. Deklarierte Experten- und Persona-Skill-Verweise

werden nur dann auf eine bereinigte ID normalisiert, wenn diese ID in der

exportierten Registry existiert. Fehlerhafte, unbekannte und normalisierte Verweise

bleiben in `issues` sichtbar; unbekannte oder ungültige Verweise werden nie zu

Endpunkten oder Persona-Kompatibilitätslinks.

Stufe `candidate_skills` nicht automatisch hoch. Bestätige sie zuerst über

einen aktiven Skill-Resolver oder Quellmetadaten.

+ ## Personas anlegen und ablegen

+ Der Kern erzeugt Karten, er erfindet keine Personas. Wer eigene Personas nutzen

+ will, legt sie **neben dem Skill** ab und baut die Karte neu:

+ ```text

+ semantic-persona-routing/

+ personas/<persona-id>.md # eine Datei je Persona

+ roles/<rolle>/SKILL.md # koordinierende Rollen und Experten

+ routing-map.json # erzeugte Karte

+ config.json # host-lokal, nie veröffentlicht

+ ```

+ Rollen liest der Builder ausschließlich aus `SKILL.md`-Dateien; Personas aus

+ jeder Markdown-Datei mit Frontmatter. Kopiere

+ [templates/persona.template.md](templates/persona.template.md) nach

+ `personas/<persona-id>.md` und fülle den Vertrag aus:

+ | Feld | Bedeutung |

+ |---|---|

+ | `name`, `type: persona` | stabile Persona-ID und Typ |

+ | `persona.display_name`, `short_name`, `gender`, `role`, `default_prompt` | Anzeige, Kurzname, Anrede, Rolle in einem Satz, Aufrufsatz des Anbieters |

+ | `parent_agents` | koordinierende Rollen, denen die Persona zugeordnet ist |

+ | `skills` | **Skill-Namen, nie Pfade** — nur diese werden zu Endpunkten aufgelöst |

+ | `optional_skills` | host-gebundene Skills; fehlen sie, bleiben sie eine sichtbare `GAP` |

+ Eine Persona darf Werkzeuge, Berechtigungen und Sicherheits-, Sperr- oder

+ Nutzerentscheidungen weder verleihen noch überschreiben; sie ist ein Overlay

+ über Rolle und Skills.

+ **Pfade:** Der Skill nennt keine Hostpfade. `config.example.json` zeigt das

+ Muster (`ellmos.skill-config.v1`, `einstellungen.paths` mit Platzhaltern wie

+ `<HOME>/<ONEDRIVE>/<TOPICS>`); die host-lokale Kopie heißt `config.json`,

+ wird beim Deploy bewahrt und nie ins Repository übernommen.

+ **Katalog bereinigen:** Eine Skill-Bibliothek mit Archiven oder Referenzkopien

+ erzeugt viele `duplicate-skill-id`-Issues. `--skills-layout catalog` nimmt nur

+ `<kategorie>/<name>/SKILL.md` und überspringt Ordner mit `_`-Präfix

+ (`_archive`, `_reference`, `_templates`):

+ ```bash

+ python scripts/build_routing_map.py \

+ --roles-dir roles --personas-dir personas \

+ --skills-dir path/to/skills --skills-layout catalog \

+ --out routing-map.json

+ ```

## Eine Anfrage routen

+ ### 0. Vorhandene Personas anbieten

+ Liegen Personas neben dem Skill (`personas/`), liste sie beim Aufruf mit

+ Anzeigename, Rolle und Skills auf und route zur passenden; nennt die Anfrage

+ keine Persona, wähle sie erst in Schritt 4. Das Format des Routing-Belegs bleibt

+ unverändert.

### 1. Koordinierende Rolle semantisch wählen

Vergleiche die Anfrage mit Rollennamen, Beschreibungen und Anwendungsfällen.

Bevorzuge die engste Rolle, die die gesamte Anfrage koordinieren kann. Halte bei

geringer Sicherheit mehrere Kandidaten sichtbar; frage den Nutzer nur, wenn die

Wahl das Ergebnis wesentlich verändert.

### 2. Experten innerhalb der Rolle wählen

Nutze nur Experten, die mit der gewählten koordinierenden Rolle verbunden sind,

sofern die Anfrage nicht eindeutig mehrere Rollen umfasst. Eine direkte

Expertenanfrage darf die koordinierende Rolle bei der Ausführung überspringen,

behält deren Verbindung aber in der Routenerklärung bei.

### 3. Ausführbare Endpunkte auflösen

Löse in dieser Reihenfolge auf:

1. `endpoint_skills` aus ausdrücklichen Quellmetadaten oder exakter Herkunft;

2. einen aktuellen externen Skill-Resolver oder lokalen Skill-Finder;

3. verifizierte `candidate_skills`;

4. eine sichtbare `GAP`, wenn kein Endpunkt existiert.

Route niemals zu einem Expertennamen, als wäre er ein installierter Skill. Ein

fehlender Endpunkt ist eine Portierungslücke und keine Erlaubnis, einen Endpunkt

zu erfinden.

Lies [endpoint-resolution.md](references/endpoint-resolution.md), wenn du eine

aktive Registry, einen lexikalischen Finder oder einen anbieterspezifischen

Skill-Loader anschließt.

### 4. Persona-Overlay anwenden

Wähle eine Persona, die der ausgewählten Rolle oder dem Experten zugeordnet ist.

Wenn mehrere Personas passen, bevorzuge eine, deren erklärte Grenzen und Stil

zur Aufgabe passen. Wende keine Persona an, wenn keine ausdrücklich verbunden

ist.

Persona-Anweisungen dürfen Sicherheitsregeln, Sperren, Nutzerentscheidungen,

berufliche Grenzen oder Werkzeugberechtigungen nicht überschreiben.

### 5. Laden und ausführen

Nutze den nativen Skill- oder Agentenlademechanismus des Anbieters. Lade vor der

Ausführung die ausgewählten aktiven Skill-Anweisungen. Halte den Router schlank;

die Ausführung gehört zum Worker oder zum aktuellen Agenten mit den geladenen

Skills.

## Routing-Beleg

Gib Folgendes zurück oder zeichne es auf:

```text

ROLE: <koordinierende Rolle oder direct>

EXPERT: <Experte oder n/a>

SKILLS: <verifizierte aktive Endpunkte>

PERSONA: <Overlay oder none>

RESOLUTION: explicit | provenance | live-resolver | verified-candidate | GAP

CONFIDENCE: high | medium | low

WHY: <ein kurzer Grund>

GAPS: <fehlende Endpunkte oder Warnungen vor veralteten Karten>

```

Erstelle die Karte neu, wenn sich Quellrollen oder Skill-Bestand ändern. Ein

aktiver Resolver darf eine veraltete Karte hinsichtlich der

Endpunktverfügbarkeit überstimmen, aber die semantische Rollentaxonomie nicht

stillschweigend umschreiben.

## Beispiel

Anfrage: „Ordne meine Belege und bereite die Übersicht für das Steuerjahr vor.“

Der Router wählt eine Büro-Koordination, danach den Steuerexperten, löst den

installierten Steuer-Skill auf und wendet schließlich eine ausdrücklich

verknüpfte, sorgfältige Steuer-Persona an. Existiert der Steuerexperte, aber

kein portabler Steuer-Skill, meldet er `GAP` und fährt nur über einen

ausdrücklich konfigurierten Ersatzweg fort.

## Änderungsprotokoll

+ ### 1.1.0 (2026-09-03)

+ - Personas anlegen und ablegen: Ablagekonvention neben dem Skill, Frontmatter-

+ Vertrag, neutrale Vorlage `templates/persona.template.md`, Pfad-Konvention mit

+ `config.example.json`, Aufruf-Verhalten (vorhandene Personas anbieten) und

+ `--skills-layout catalog` gegen doppelte Skill-IDs aus Archiv- und Referenzkopien.

### 1.0.0 (2026-07-28)

- Die anbieterneutrale Rollen-, Experten- und Skill-Kette aus einem bewährten

Domänen-Router extrahiert und portable Kartenerstellung mit sichtbaren

Endpunktlücken ergänzt.