Dify Workflow DSL (Self-Hosted)

---

name: dify-workflow

description: Use when creating, editing, debugging, or validating Dify workflow DSL for self-hosted Dify. Start from an exported workflow of the target instance, edit minimally, and verify by re-importing.

---

# Dify Workflow DSL (Self-Hosted)

Ein konsolidierter Skill fuer Dify-Workflow-DSL: Authoring, Editing, Debugging, Referenzen, Templates und lokale Validierung in einem Paket.

**Arbeitsbereich:** Workflow-DSL, Import-/Export-nahe Aenderungen und YAML-Validierung

**Nicht zustaendig:** App-, Prompt-, Dataset- oder Knowledge-Base-Orchestrierung. Dafuer den Skill [`../dify/SKILL.md`](../dify/SKILL.md) verwenden.

Trigger Conditions

Use when:

Scope Boundaries

Nutze **diesen** Skill fuer:

Nutze **`dify`** fuer:

Expert Domains

Dieser Skill soll langfristig ein echter self-hosted-Dify-Workflow-Experte fuer diese Bereiche werden:

Rapid Triage

Bleibe in **`dify-workflow`**, wenn der User eines davon liefert oder verlangt:

Bleibe **nicht** hier, wenn das Problem per App-, Prompt- oder Dataset-Operation loesbar ist. Dann an `dify` zurueckgeben.

App-, Prompt- oder Dataset-Aufgaben sind in der Regel **Management-Operationen** und gehoeren deshalb zu `dify`, nicht zu `dify-workflow`.

Operating Principles

1. **Export first**: Ein Export der Zielinstanz ist immer die Quelle der Wahrheit.

2. **Minimal edits**: Nur gezielte Aenderungen, keine Voll-Neuschreibung ohne Not.

3. **Version aware**: Versions- und Plugin-Unterschiede explizit pruefen.

4. **Secrets stay out of content**: Keine API-Keys in YAML, Prompts oder Beispielen.

5. **Validate before import**: Lokal pruefen, dann auf derselben Zielinstanz importieren.

Recommended Workflow

1. Exportiere einen bekannten, funktionierenden Workflow aus der Zielinstanz.

2. Leite Struktur, Version und Feldnamen aus diesem Export ab.

3. Nutze Templates und Referenzen aus diesem Skill nur als Hilfestellung, nicht als starre Wahrheit.

4. Bearbeite die DSL minimal statt sie komplett neu zu erfinden.

5. Validiere lokal und pruefe danach den Import in derselben Zielinstanz.

Wenn **kein Export** vorliegt:

1. klar sagen: kein Export vorhanden,

2. nicht so tun, als sei ein Template schon produktionsreif,

3. die Antwort explizit als unverified draft markieren,

4. klar sagen, dass der Workflow ohne Export nicht direkt importierbar ist,

5. vor jeder riskanten Ueberschreibung einen bestehenden Export oder ein anderes belastbares Backup fuer Rollback verlangen,

6. auf Export der Zielinstanz bestehen, sobald echte Importfaehigkeit gefordert ist.

Critical Rules

Rule 1: Export First

Rule 2: Variable Syntax Must Be Exact

{{#NODE_ID.VARIABLE_NAME#}}

Wrong examples:

Rule 3: Code Node Outputs Must Match

Wenn ein Code-Node `{"result": ...}` oder andere Felder zurueckgibt, muessen diese Felder im `outputs`-Schema deklariert sein.

Rule 4: Secrets Stay Outside the DSL

Rule 5: Validate Changed Paths, Not Just Theory

Nach jeder relevanten Aenderung:

1. lokale YAML-Pruefung ausfuehren,

2. betroffene Outputs und Variablen-Verweise gegen die geaenderte Struktur lesen,

3. Re-Import in derselben Zielinstanz empfehlen oder durchfuehren, wenn moeglich.

Package Contents

Available References

Das uebergeordnete Themen- und Quellen-Backlog liegt unter `../../../research/`.

Templates And Assets

Local Scripts

Beispiele:

# Node-IDs erzeugen
python3 scripts/generate_id.py 5

# Workflow lokal validieren
python3 scripts/validate_workflow.py /absolute/path/to/workflow.yaml

Safety Notes

Practical Editing Checklist

1. Start-/End-Nodes vorhanden?

2. Sind alle Node-IDs eindeutig?

3. Referenzieren alle Edges existierende Nodes?

4. Stimmen `sourceHandle` und `targetHandle` zum Node-Typ?

5. Ist die Variablen-Syntax exakt?

6. Stimmen Code-Outputs mit `outputs` ueberein?

7. Sind Provider-/Plugin-Abhaengigkeiten und Versionen zur Zielinstanz passend?

8. Wurde der Import in der Zielinstanz getestet?

9. Ist ohne Export klar markiert, dass es nur ein Draft ist?

10. Gibt es vor riskanten Ersetzungen einen belastbaren Backup- oder Rollback-Pfad?

Import Error Triage

Wenn ein Re-Import scheitert, in dieser Reihenfolge pruefen:

1. `validate_workflow.py` zuerst laufen lassen.

2. Node-IDs und Edge-Referenzen pruefen.

3. `sourceHandle` und `targetHandle` gegen den betroffenen Node-Typ pruefen.

4. `outputs` von Code-Nodes gegen ihre Rueckgabefelder pruefen.

5. Variable-Syntax und abgeleitete Verweise erneut lesen.

6. Minimalen Fix statt Full Rewrite vorbereiten.

7. Erst danach groessere Strukturfehler oder Versionsunterschiede vermuten.

Recommended Response Pattern

Wenn ein User eine Workflow-Aenderung will:

1. Frage nach Export oder bestehender DSL-Datei.

2. Klaere Zielinstanz und Dify-Version, falls unklar.

3. Schlage minimale Aenderungen statt Full Rewrite vor.

4. Verweise fuer Details gezielt auf Templates, Referenzen oder Validator.

5. Schliesse mit Re-Import-/Smoke-Check-Schritten auf derselben Zielinstanz ab.

Praktische Rueckgabe an `dify`, falls die Anfrage falsch gelandet ist:

Das ist wahrscheinlich keine DSL-Aenderung, sondern eine Management-Operation an App, Prompt oder Dataset. Ich wechsle dafuer auf `dify`, damit die Management-Operation ohne unnötige Workflow-Komplexitaet umgesetzt wird.

Useful References