Skills
Skills sind strukturierte Wissenspakete, die jedem Agenten seine Domänenexpertise verleihen. Sie sind nicht nur Prompts — sie enthalten Ausführungsprotokolle, Tech-Stack-Referenzen, Code-Vorlagen, Fehler-Playbooks, Qualitätschecklisten und Few-Shot-Beispiele, organisiert in einer Zwei-Schichten-Architektur, die auf Token-Effizienz ausgelegt ist.
Das Zwei-Schichten-Design
Schicht 1: SKILL.md (~800 Bytes, immer geladen)
Jeder Skill hat eine SKILL.md-Datei in seinem Stammverzeichnis. Diese wird immer in das Kontextfenster geladen, wenn der Skill referenziert wird. Sie enthält:
- YAML-Frontmatter mit
nameunddescription(verwendet für Routing und Anzeige) - Wann verwenden / Wann NICHT verwenden — explizite Aktivierungsbedingungen
- Kernregeln — die 5-15 kritischsten Einschränkungen für die Domäne
- Architekturübersicht — wie Code strukturiert sein sollte
- Bibliotheksliste — genehmigte Abhängigkeiten und deren Zwecke
- Referenzen — Verweise auf Schicht-2-Ressourcen (werden nie automatisch geladen)
Beispiel-Frontmatter:
---
name: oma-frontend
description: Frontend specialist for React, Next.js, TypeScript with FSD-lite architecture, shadcn/ui, and design system alignment. Use for UI, component, page, layout, CSS, Tailwind, and shadcn work.
---
Das description-Feld ist entscheidend — es enthält die Routing-Keywords, die das Skill-Routing-System zur Zuordnung von Aufgaben zu Agenten verwendet.
Schicht 2: resources/ (bedarfsgesteuert geladen)
Das resources/-Verzeichnis enthält vertiefte Ausführungskenntnisse. Diese Dateien werden nur geladen, wenn:
- Der Agent explizit aufgerufen wird (via
/commandoder Agenten-Skills-Feld) - Die spezifische Ressource für den aktuellen Aufgabentyp und Schwierigkeitsgrad benötigt wird
Dieses bedarfsgesteuerte Laden wird durch den Context-Loading-Leitfaden (.agents/skills/_shared/core/context-loading.md) gesteuert, der Aufgabentypen den erforderlichen Ressourcen pro Agent zuordnet.
Beispiel der Dateistruktur
.agents/skills/oma-frontend/
├── SKILL.md <- Schicht 1: immer geladen (~800 Bytes)
└── resources/
├── execution-protocol.md <- Schicht 2: Schritt-für-Schritt-Workflow
├── tech-stack.md <- Schicht 2: detaillierte Technologiespezifikationen
├── tailwind-rules.md <- Schicht 2: Tailwind-spezifische Konventionen
├── component-template.tsx <- Schicht 2: React-Komponentenvorlage
├── snippets.md <- Schicht 2: kopierbereite Code-Muster
├── error-playbook.md <- Schicht 2: Fehlerbehandlungsverfahren
├── checklist.md <- Schicht 2: Qualitätsverifikationscheckliste
└── examples/ <- Schicht 2: Few-Shot-Ein-/Ausgabebeispiele
└── examples.md
.agents/skills/oma-backend/
├── SKILL.md
├── resources/
│ ├── execution-protocol.md
│ ├── examples.md
│ ├── orm-reference.md <- Domänenspezifisch (ORM-Abfragen, N+1, Transaktionen)
│ ├── checklist.md
│ └── error-playbook.md
└── stack/ <- Generiert durch /stack-set (sprachspezifisch)
├── stack.yaml
├── tech-stack.md
├── snippets.md
└── api-template.*
.agents/skills/oma-design/
├── SKILL.md
├── resources/
│ ├── execution-protocol.md
│ ├── anti-patterns.md
│ ├── checklist.md
│ ├── design-md-spec.md
│ ├── design-tokens.md
│ ├── prompt-enhancement.md
│ ├── stitch-integration.md
│ └── error-playbook.md
├── reference/ <- Vertieftes Referenzmaterial
│ ├── typography.md
│ ├── color-and-contrast.md
│ ├── spatial-design.md
│ ├── motion-design.md
│ ├── responsive-design.md
│ ├── component-patterns.md
│ ├── accessibility.md
│ └── shader-and-3d.md
└── examples/
├── design-context-example.md
└── landing-page-prompt.md
Ressourcentypen pro Skill
| Ressourcentyp | Dateinamenmuster | Zweck | Wann geladen |
|---|---|---|---|
| Ausführungsprotokoll | execution-protocol.md | Schritt-für-Schritt-Workflow: Analysieren -> Planen -> Implementieren -> Verifizieren | Immer (mit SKILL.md) |
| Tech-Stack | tech-stack.md | Detaillierte Technologiespezifikationen, Versionen, Konfiguration | Komplexe Aufgaben |
| Fehler-Playbook | error-playbook.md | Wiederherstellungsverfahren mit "3-Strikes"-Eskalation | Nur bei Fehlern |
| Checkliste | checklist.md | Domänenspezifische Qualitätsverifikation | Beim Verifikationsschritt |
| Snippets | snippets.md | Kopierbereite Code-Muster | Mittlere/komplexe Aufgaben |
| Beispiele | examples.md oder examples/ | Few-Shot-Ein-/Ausgabebeispiele für das LLM | Mittlere/komplexe Aufgaben |
| Varianten | stack/-Verzeichnis | Sprach-/Framework-spezifische Referenzen (generiert durch /stack-set) | Wenn Stack vorhanden |
| Vorlagen | component-template.tsx, screen-template.dart | Boilerplate-Dateivorlagen | Bei Komponentenerstellung |
| Domänenreferenz | orm-reference.md, anti-patterns.md usw. | Vertiefte Domänenkenntnisse für spezifische Teilaufgaben | Aufgabentypspezifisch |
Gemeinsame Ressourcen (_shared/)
Alle Agenten teilen gemeinsame Grundlagen aus .agents/skills/_shared/. Diese sind in drei Kategorien organisiert:
Kernressourcen (.agents/skills/_shared/core/)
| Ressource | Zweck | Wann geladen |
|---|---|---|
skill-routing.md | Ordnet Aufgaben-Keywords dem richtigen Agenten zu. Enthält die Skill-Agent-Zuordnungstabelle, Routing-Muster für komplexe Anfragen, Inter-Agent-Abhängigkeitsregeln, Eskalationsregeln und Zug-Limit-Leitfaden. | Referenziert von Orchestrator- und Koordinations-Skills |
context-loading.md | Definiert, welche Ressourcen für welchen Aufgabentyp und Schwierigkeitsgrad geladen werden. Enthält pro-Agent-Aufgabentyp-zu-Ressource-Zuordnungstabellen und bedingte Protokoll-Ladetrigger. | Beim Workflow-Start (Schritt 0 / Phase 0) |
prompt-structure.md | Definiert die vier Elemente, die jeder Aufgaben-Prompt enthalten muss: Ziel, Kontext, Einschränkungen, Fertig-wenn. Enthält Vorlagen für PM-, Implementierungs- und QA-Agenten. Listet Anti-Patterns auf (Beginn mit nur einem Ziel). | Referenziert von PM-Agent und allen Workflows |
clarification-protocol.md | Definiert Unsicherheitsebenen (LOW/MEDIUM/HIGH) mit Aktionen für jede Ebene. Enthält Unsicherheitsauslöser, Eskalationsvorlagen, erforderliche Verifikationselemente pro Agententyp und Subagenten-Modus-Verhalten. | Bei mehrdeutigen Anforderungen |
context-budget.md | Token-Budget-Verwaltung. Definiert Strategie zum Dateilesen (verwende find_symbol, nicht read_file), Ressourcenladebudgets pro Modellebene (Flash: ~3.100 Tokens / Pro: ~5.000 Tokens), Behandlung großer Dateien und Symptome bei Kontextüberlauf. | Beim Workflow-Start |
difficulty-guide.md | Kriterien zur Klassifizierung von Aufgaben als Einfach/Mittel/Komplex. Definiert erwartete Zugzahlen, Protokollverzweigung (Schnellweg / Standard / Erweitert) und Fehleinschätzungskorrektur. | Beim Aufgabenstart (Schritt 0) |
reasoning-templates.md | Strukturierte Reasoning-Ausfüllvorlagen für häufige Entscheidungsmuster (z. B. Explorations-Entscheidungsvorlage #6, verwendet von der Explorationsschleife). | Bei komplexen Entscheidungen |
quality-principles.md | 4 universelle Qualitätsprinzipien, die über alle Agenten hinweg angewendet werden. | Beim Workflow-Start für qualitätsfokussierte Workflows (ultrawork) |
vendor-detection.md | Protokoll zur Erkennung der aktuellen Laufzeitumgebung (Claude Code, Codex CLI, Gemini CLI, Antigravity, CLI-Fallback). Verwendet Markerprüfungen: Agent-Tool = Claude Code, apply_patch = Codex, @-Syntax = Gemini. | Beim Workflow-Start |
session-metrics.md | Clarification-Debt-Bewertung (CD) und Sitzungsmetrik-Verfolgung. Definiert Ereignistypen (clarify +10, correct +25, redo +40), Schwellenwerte (CD >= 50 = RCA, CD >= 80 = Pause) und Integrationspunkte. | Während Orchestrierungssitzungen |
common-checklist.md | Universelle Qualitätscheckliste, die bei der abschließenden Verifikation komplexer Aufgaben angewendet wird (zusätzlich zu agentenspezifischen Checklisten). | Verifikationsschritt komplexer Aufgaben |
lessons-learned.md | Sammlung vergangener Sitzungserkenntnisse, automatisch generiert aus Clarification-Debt-Überschreitungen und verworfenen Experimenten. Nach Domänenabschnitten organisiert. | Referenziert nach Fehlern und am Sitzungsende |
api-contracts/ | Verzeichnis mit API-Vertragsvorlage und generierten Verträgen. template.md definiert das Pro-Endpunkt-Format (Methode, Pfad, Anfrage-/Antwort-Schemata, Auth, Fehler). | Bei geplanter domänenübergreifender Arbeit |
Laufzeit-Ressourcen (.agents/skills/_shared/runtime/)
| Ressource | Zweck |
|---|---|
memory-protocol.md | Memory-Dateiformat und -Operationen für CLI-Subagenten. Definiert On-Start-, During-Execution- und On-Completion-Protokolle mit konfigurierbaren Memory-Tools (read/write/edit). Enthält Experimentverfolgungserweiterung. |
execution-protocols/claude.md | Claude-Code-spezifische Ausführungsmuster. Wird von oma agent:spawn injiziert, wenn der Vendor claude ist. |
execution-protocols/gemini.md | Gemini-CLI-spezifische Ausführungsmuster. |
execution-protocols/codex.md | Codex-CLI-spezifische Ausführungsmuster. |
execution-protocols/qwen.md | Qwen-CLI-spezifische Ausführungsmuster. |
Vendor-spezifische Ausführungsprotokolle werden automatisch von oma agent:spawn injiziert — Agenten müssen sie nicht manuell laden.
Bedingte Ressourcen (.agents/skills/_shared/conditional/)
Diese werden nur geladen, wenn bestimmte Bedingungen während der Ausführung erfüllt sind:
| Ressource | Auslösebedingung | Geladen von | Ungefähre Tokens |
|---|---|---|---|
quality-score.md | VERIFY- oder SHIP-Phase beginnt in einem Workflow, der Qualitätsmessung unterstützt | Orchestrator (wird an QA-Agent-Prompt übergeben) | ~250 |
experiment-ledger.md | Erstes Experiment wird aufgezeichnet, nachdem eine IMPL-Baseline etabliert wurde | Orchestrator (inline, nach Baseline-Messung) | ~250 |
exploration-loop.md | Dasselbe Gate scheitert zweimal beim selben Problem | Orchestrator (inline, vor dem Starten von Hypothesen-Agenten) | ~250 |
Budgetauswirkung: ungefähr 750 Tokens insgesamt, wenn alle 3 geladen werden. Da das Laden bedingt ist, laden typische Sitzungen 1-2 davon. Das Flash-Tier-Budget bleibt innerhalb der ungefähr 3.100 Token-Zuweisung.
Wie Skills über skill-routing.md geroutet werden
Die Skill-Routing-Karte definiert, wie Aufgaben Agenten zugeordnet werden:
Einfaches Routing (einzelne Domäne)
Ein Prompt mit "Build a login form with Tailwind CSS" stimmt mit den Keywords UI, component, form, Tailwind überein und wird an oma-frontend weitergeleitet.
Routing komplexer Anfragen
Multi-Domänen-Anfragen folgen etablierten Ausführungsreihenfolgen:
| Anfragemuster | Ausführungsreihenfolge |
|---|---|
| "Create a fullstack app" | oma-pm -> (oma-backend + oma-frontend) parallel -> oma-qa |
| "Create a mobile app" | oma-pm -> (oma-backend + oma-mobile) parallel -> oma-qa |
| "Fix bug and review" | oma-debug -> oma-qa |
| "Design and build a landing page" | oma-design -> oma-frontend |
| "I have an idea for a feature" | oma-brainstorm -> oma-pm -> relevante Agenten -> oma-qa |
| "Do everything automatically" | oma-orchestrator (intern: oma-pm -> Agenten -> oma-qa) |
Inter-Agent-Abhängigkeitsregeln
Können parallel laufen (keine Abhängigkeiten):
- oma-backend + oma-frontend (wenn API-Vertrag vorab definiert ist)
- oma-backend + oma-mobile (wenn API-Vertrag vorab definiert ist)
- oma-frontend + oma-mobile (unabhängig voneinander)
Müssen sequenziell laufen:
- oma-brainstorm -> oma-pm (Design kommt vor Planung)
- oma-pm -> alle anderen Agenten (Planung kommt zuerst)
- Implementierungsagent -> oma-qa (Review nach Implementierung)
- oma-backend -> oma-frontend/oma-mobile (wenn kein vorab definierter API-Vertrag)
QA ist immer zuletzt, außer wenn der Benutzer nur ein Review bestimmter Dateien anfordert.
Token-Einsparungsberechnung
Betrachten Sie eine 5-Agenten-Orchestrierungssitzung (pm, backend, frontend, mobile, qa):
Ohne progressive Offenlegung:
- Jeder Agent lädt alle Ressourcen: ~4.000 Tokens pro Agent
- Gesamt: 5 x 4.000 = 20.000 Tokens verbraucht, bevor Arbeit beginnt
Mit progressiver Offenlegung:
- Nur Schicht 1 für alle Agenten: 5 x 800 = 4.000 Tokens
- Schicht 2 nur für aktive Agenten geladen (typischerweise 1-2 gleichzeitig): +1.500 Tokens
- Gesamt: ~5.500 Tokens
Einsparung: ungefähr 72-75 %
Bei Flash-Tier-Modellen (128K Kontext) ist dies der Unterschied zwischen 108K verfügbaren Tokens für Arbeit und 125K Tokens — eine erhebliche Marge für komplexe Aufgaben.
Ressourcenladen nach Aufgabenschwierigkeit
Der Schwierigkeitsleitfaden klassifiziert Aufgaben in drei Stufen, die bestimmen, wie viel von Schicht 2 geladen wird:
Einfach (3-5 erwartete Züge)
Einzelne Dateiänderung, klare Anforderungen, Wiederholung vorhandener Muster.
Lädt: nur execution-protocol.md. Analyse überspringen, direkt zur Implementierung mit minimaler Checkliste.
Mittel (8-15 erwartete Züge)
2-3 Dateiänderungen, einige Designentscheidungen nötig, Anwendung von Mustern auf neue Domänen.
Lädt: execution-protocol.md + examples.md. Standardprotokoll mit kurzer Analyse und vollständiger Verifikation.
Komplex (15-25 erwartete Züge)
4+ Dateiänderungen, Architekturentscheidungen erforderlich, Einführung neuer Muster, Abhängigkeiten von anderen Agenten.
Lädt: execution-protocol.md + examples.md + tech-stack.md + snippets.md. Erweitertes Protokoll mit Checkpoints, Fortschrittsaufzeichnung während der Ausführung und vollständiger Verifikation einschließlich common-checklist.md.
Context-Loading-Aufgabenzuordnungen (pro Agent)
Der Context-Loading-Leitfaden bietet detaillierte Aufgabentyp-zu-Ressource-Zuordnungen. Hier sind die wichtigsten Zuordnungen:
Backend-Agent
| Aufgabentyp | Erforderliche Ressourcen |
|---|---|
| CRUD-API-Erstellung | stack/snippets.md (Route, Schema, Modell, Test) |
| Authentifizierung | stack/snippets.md (JWT, Passwort) + stack/tech-stack.md |
| DB-Migration | stack/snippets.md (Migration) |
| Performance-Optimierung | examples.md (N+1-Beispiel) |
| Vorhandenen Code modifizieren | examples.md + Serena MCP |
Frontend-Agent
| Aufgabentyp | Erforderliche Ressourcen |
|---|---|
| Komponentenerstellung | snippets.md + component-template.tsx |
| Formularimplementierung | snippets.md (Formular + Zod) |
| API-Integration | snippets.md (TanStack Query) |
| Styling | tailwind-rules.md |
| Seitenlayout | snippets.md (Grid) + examples.md |
Design-Agent
| Aufgabentyp | Erforderliche Ressourcen |
|---|---|
| Design-System-Erstellung | reference/typography.md + reference/color-and-contrast.md + reference/spatial-design.md + design-md-spec.md |
| Landingpage-Design | reference/component-patterns.md + reference/motion-design.md + prompt-enhancement.md + examples/landing-page-prompt.md |
| Design-Audit | checklist.md + anti-patterns.md |
| Design-Token-Export | design-tokens.md |
| 3D- / Shader-Effekte | reference/shader-and-3d.md + reference/motion-design.md |
| Barrierefreiheits-Review | reference/accessibility.md + checklist.md |
QA-Agent
| Aufgabentyp | Erforderliche Ressourcen |
|---|---|
| Sicherheits-Review | checklist.md (Sicherheitsabschnitt) |
| Performance-Review | checklist.md (Performance-Abschnitt) |
| Barrierefreiheits-Review | checklist.md (Barrierefreiheitsabschnitt) |
| Vollständiges Audit | checklist.md (komplett) + self-check.md |
| Qualitätsbewertung | quality-score.md (bedingt) |
Orchestrator-Prompt-Zusammenstellung
Wenn der Orchestrator Prompts für Subagenten zusammenstellt, enthält er nur aufgabenrelevante Ressourcen:
- Kernregeln-Abschnitt der SKILL.md des Agenten
execution-protocol.md- Ressourcen, die dem spezifischen Aufgabentyp entsprechen (aus den obigen Zuordnungen)
error-playbook.md(immer enthalten — Fehlerbehandlung ist essenziell)- Serena Memory Protocol (CLI-Modus)
Diese zielgerichtete Zusammenstellung vermeidet das Laden unnötiger Ressourcen und maximiert den verfügbaren Kontext des Subagenten für die eigentliche Arbeit.