---
name: "merge-skill"
description: "Bestehenden Skill mit neuem Skill-Material (ZIP/Text/Datei) zu einer perfektionierten Hybrid-Version mergen."
---

# merge-skill

Wiederholbare Methode, um einen **bestehenden, funktionierenden Skill** mit **neu eingebrachtem Skill-Material** (ZIP, Text-Paste, Markdown-File, Claude.ai-Export, GitHub-Skill etc.) zu einer **perfektionierten Hybrid-Version** zu kombinieren — **ausschließlich über lokale KI-Instanzen**, um Token-Kosten zu sparen und Daten lokal zu halten.

## 🎯 Kernregel: LOKAL-FIRST

> **Dieser Skill läuft IMMER über lokale Modelle. Cloud-Cloud-Modelle nur als expliziter Fallback wenn lokal offline.**

### Routing-Reihenfolge

1. **Mac Studio** (`macstudio/qwen3.6:latest`) — Standard, ~72 tok/s, qwen3.6 hot im RAM via `OLLAMA_KEEP_ALIVE=-1`
2. **LM Studio Win11** (`lmstudio/<modell>`) — Fallback wenn Mac offline (via Cloudflare-Tunnel)
3. **Cloud (Sonnet/Opus)** — NUR wenn beide lokalen Instanzen offline + User explizit OK gibt

### Mechanik

Skill-Merging delegieren an Mac-Studio via `sessions_spawn`:

```
sessions_spawn
  model: "macstudio/qwen3.6:latest"
  lightContext: true                  ← PFLICHT! sonst Context-Overflow
  task: <Merge-Brief mit beiden Skill-Inhalten als Input>
```

**⚠️ `lightContext: true` ist Pflicht** — qwen3.6 hat kleineres Context-Fenster. Ohne lightContext bricht der Bootstrap.

Alternativ One-Shot über Mac-Backend für reine Text-Transformationen:
```
POST /api/macstudio/test  
Body: {"model": "qwen3.6:latest", "prompt": "<Merge-Prompt>"}
```

### Lokale Verfügbarkeit prüfen

Vor jedem Merge: `read data/healthcheck-last.json` — wenn Mac als "warning" gelistet ist (offline), auf LM Studio ausweichen. Wenn beide offline: User informieren und **fragen** ob Cloud-Fallback OK ist.

## Wann verwenden

- User lädt ZIP/Skill-Bundle hoch mit „check mal das File" / „update meinen Skill X" / „merge das mit dem bestehenden"
- User pastet Skill-Inhalt direkt in den Chat und will ihn integrieren
- Es existiert bereits ein gleichnamiger oder thematisch identischer Skill in `~/.openclaw/workspace/skills/`
- Beim direkten 1:1-Ersetzen würden **Funktionen brechen** (fremde APIs, andere Tool-Namen, andere Sprache als die installierte Konvention)
- Migration von Claude.ai/Anthropic-Skills nach OpenClaw

## Kernprinzip beim Mergen

> **Niemals blind ersetzen. Immer evaluieren, dann hybridisieren — lokal.**

Skills aus anderen Ökosystemen (Claude.ai, ChatGPT GPTs, Cursor-Rules etc.) nutzen oft **Tool-Endpoints die in OpenClaw nicht existieren** (`Yahoo/get_stock_profile`, `web_search.brave`, etc.). Roh ersetzen → Skill ist tot. Roh ignorieren → User-Wertschöpfung weg. Hybridisierung ist die Antwort — und qwen3.6 kann diese Text-Synthese problemlos.

## Workflow

### 1. Material in den Griff bekommen

ZIP, Paste oder File. Bei ZIPs aus `media://inbound/`:

- `read` zeigt nur kaputten UTF-8-Hex → **nicht** auf Klartext-Inhalt schließen
- `exec`/`unzip` ist oft per Allowlist blockiert
- **Pragmatisch:** User bitten den Inhalt von SKILL.md + References als Text zu pasten (30 Sekunden, immer zuverlässig)
- Alternativ: User schickt ZIP via SCP/SFTP an einen lesbaren Pfad

### 2. Bestehenden Skill lesen (lokal, Cloud-Tool-Calls)

```
read /root/.openclaw/workspace/skills/<skill-name>/SKILL.md
read /root/.openclaw/workspace/skills/<skill-name>/references/  (falls existiert)
```

Hinweis: `read` ist ein lokales Filesystem-Tool, kostet keine Cloud-Tokens.

Wenn der Skill noch nicht existiert: Es ist kein Merge, sondern ein normaler `skill_workshop action=create`. Stoppen, neu anlegen.

### 3. Health-Check (lokale KI verfügbar?)

```
read /root/.openclaw/workspace/data/healthcheck-last.json
```

Prüfen: `macstudio` Status. Wenn online → weiter. Wenn offline → LM Studio probieren (`http://localhost:1234` oder Tunnel-URL aus TOOLS.md).

### 4. Inkompatibilitäts-Check delegieren an Mac

Statt selbst zu analysieren, spawnt der Hauptassistent eine kurze Mac-Subagent-Session:

```
sessions_spawn
  model: "macstudio/qwen3.6:latest"
  lightContext: true
  task: |
    Du bekommst zwei Skill-Versionen. Analysiere Inkompatibilitäten und gib eine 
    Vergleichstabelle aus.
    
    [ALT - bestehender Skill]
    <Inhalt SKILL.md alt>
    
    [NEU - User-Material]
    <Inhalt SKILL.md neu>
    
    Output (deutsch, knapp):
    | Achse | Alt | Neu | Funktioniert hier? |
    
    Prüfe: Sprache, Tool-Namen (web_fetch, code_execution, read, write, exec, 
    image_generate existieren — alles andere ist verdächtig), API-Endpoints 
    (Yahoo/get_*, <Vendor>/<action> = nicht hier verfügbar), Datenquellen, 
    Output-Struktur, Disclaimer/Sicherheit.
    
    Empfiehl eine Option: Hybrid / Replace / Nur-Referenz.
```

Subagent liefert Tabelle + Empfehlung zurück.

### 5. Optionen-Frage an den User

Immer **drei klare Optionen** anbieten (basierend auf Subagent-Output):

**A) Hybrid (Standard-Empfehlung)** — Bestes aus beiden Welten:
- Funktionierende Mechanik (Tools/APIs) aus dem alten Skill behalten
- Strukturierte Doku/Workflows/Templates aus dem neuen übernehmen
- Material aus neuem ZIP als zusätzliche `references/<topic>.md` ablegen

**B) Roh ersetzen** — Nur empfehlen wenn der neue Skill **wirklich funktioniert** (alle Tools existieren, gleiche Sprache, gleicher Stil)

**C) Nur Referenz hinzufügen** — Alten Skill 100% behalten, neues Material kommt nur als zusätzliche Doku ins `references/` Verzeichnis

User wählt. Niemals selbst entscheiden.

### 6. Hybrid bauen — DELEGIERT an Mac Studio

Bei Option A: ZWEITE Subagent-Session mit klarem Merge-Brief:

```
sessions_spawn
  model: "macstudio/qwen3.6:latest"
  lightContext: true
  task: |
    Merge zwei Skills zu einer Hybrid-Version.
    
    REGELN:
    1. Sprache: Deutsch (User-Konvention)
    2. Frontmatter --- mit name + description (max 160 Bytes!)
    3. Tools NUR aus OpenClaw-Set: web_fetch, web_search, code_execution, 
       read/write/edit, exec, image_generate, sessions_spawn
    4. Fremde APIs (Yahoo/get_*, <Vendor>/<action>) → via Translation-Layer auf 
       web_fetch <URL> umschreiben
    5. Disclaimer aus altem Skill BEWAHREN (Finance/Health/Law-Themen)
    6. Multi-Source bevorzugen (mehr Quellen = robuster)
    7. Output-Template strukturieren mit Markdown-Tabellen wo sinnvoll
    8. Quick-Commands-Tabelle am Ende (User-Frage → Workflow)
    9. Fallstricke aus beiden Skills sammeln, dedupen
    10. Format: clean Markdown, keine HTML-Tags
    
    REIHENFOLGE im Output:
    1. Frontmatter
    2. Header (1-2 Sätze)
    3. "Wann verwenden"
    4. Datenquellen-Tabelle
    5. Workflow-Schritte
    6. Output-Template
    7. Charts/Visualisierung (nur wenn relevant)
    8. Disclaimer
    9. Fallstricke
    10. Quick-Commands
    
    [ALT]
    <SKILL.md alt>
    
    [NEU]
    <SKILL.md neu>
    
    Liefere NUR den fertigen SKILL.md-Inhalt, kein Pre-Amble.
```

Subagent-Output wird als `proposal_content` für `skill_workshop action=update` verwendet.

### 7. Support-Files extrahieren (auch lokal!)

Wenn das neue Material API-/URL-Schemas/Datenpunkte beschreibt → dritte (kurze) Subagent-Session:

```
sessions_spawn
  model: "macstudio/qwen3.6:latest"
  lightContext: true
  task: |
    Extrahiere aus folgendem Material eine saubere Referenz-Markdown-Datei 
    für references/<topic>.md.
    Behalte URL-Schemas, Datenpunkte, Code-Snippets. Übersetze API-Endpoints 
    auf OpenClaw-Tools (web_fetch, code_execution mit yfinance etc.).
    
    [MATERIAL]
    <Inhalt z.B. yahoo-api.md neu>
    
    Output: NUR Markdown-Inhalt für die Datei.
```

### 8. Proposal einreichen (Hauptassistent, lokales Tool)

```
skill_workshop action=update
  skill_name=<existing-skill-name>
  description=<aktualisierte kurze Beschreibung, max 160 Bytes>
  goal=<klar: Hybrid-Merge, Quellen genannt, User-Wahl dokumentiert, "via Mac Studio lokal">
  evidence=<Was der User geliefert hat + welche Option er wählte + welches Modell den Merge gemacht hat>
  proposal_content=<Output aus Schritt 6>
  support_files=[{path: "references/<x>.md", content: "<Output aus Schritt 7>"}]
```

### 9. Anwenden (nur nach User-Bestätigung)

Wenn User die Option A explizit gewählt hat → `skill_workshop action=apply proposal_id=<id>`.

Wenn User nur „mach was passt" sagt → erst Proposal zeigen, dann Bestätigung holen, dann apply.

### 10. Validierung & Doku

Nach Apply:
- Kurze Zusammenfassung was sich geändert hat (3-5 Bullet Points)
- Ein **konkretes Test-Beispiel** anbieten („Soll ich's gleich an XYZ testen?")
- Bei großen Merges: `memory/YYYY-MM-DD.md` Eintrag erwägen mit Hinweis „via Mac Studio gemerged"

## Spezial-Fall: Claude.ai-Skill-Imports

Claude.ai-Skills haben oft:
- Tool-References wie `<Vendor>/<action>` (z.B. `Yahoo/get_stock_profile`) → **existieren nicht in OpenClaw**
- `Read`-Tool für File-Includes → bei uns ist es `read`
- Englische Defaults → User-Workspace meist Deutsch
- Kein `web_fetch` als Standard-Datenquelle → bei uns Hauptweg

**Translation-Layer (im Merge-Prompt an Mac mitgeben):**

| Claude.ai-Pattern | OpenClaw-Entsprechung |
|---|---|
| `Yahoo/get_stock_profile(T)` | `web_fetch https://finance.yahoo.com/quote/<T>/profile` |
| `Read("references/foo.md")` | `read <skill-path>/references/foo.md` |
| `WebSearch(q)` | `web_search query=<q>` |
| `<Vendor>/<API>` allgemein | `web_fetch <Vendor-URL>` oder `code_execution` mit Python-SDK |

## Fallback-Hierarchie bei lokaler Nicht-Verfügbarkeit

| Szenario | Aktion |
|---|---|
| Mac online | Standard, alle Merge-Schritte via `macstudio/qwen3.6:latest` |
| Mac offline, LM Studio online | Switch zu `lmstudio/<aktuelles-modell>` (siehe TOOLS.md) |
| Beide offline | User informieren, fragen ob Cloud-Fallback OK. NIEMALS still cloud nehmen. |
| User lehnt Cloud ab | Merge auf später vertagen, Proposal nicht erstellen |

## Fallstricke

- ⚠️ **NIEMALS** den Merge selbst (im Cloud-Hauptassistent) durchführen — IMMER an Mac/LM Studio delegieren
- ⚠️ **`lightContext: true`** bei jedem `sessions_spawn` zu Mac — sonst Context-Overflow
- ⚠️ qwen3.6 Context ~32K → bei riesigen Skills (>20KB) ggf. in 2 Pässen mergen (Frontmatter+Workflow erst, dann References)
- ⚠️ **Niemals** ZIP-Inhalt aus `media://` als Klartext lesen — die DEFLATE-Bytes kommen kaputt zurück
- ⚠️ Skills haben **nicht** automatisch `exec`-Rechte zum Entpacken
- ⚠️ Description-Feld bei `skill_workshop` ist **160 Bytes** hard cap
- ⚠️ Bei Updates **nie** existierende Skills via `write` direkt überschreiben — durch `skill_workshop` gehen
- ⚠️ Support-Files (`references/`) sind im Proposal **eigene Einträge** — nicht in `proposal_content` reinpacken
- ⚠️ Wenn der alte Skill Disclaimer hat (Finance/Health/Law) → diese **immer** behalten
- ⚠️ Mac-Tunnel-URL wechselt bei Reboot → bei Fehler ggf. neue URL holen (siehe MEMORY.md / mac-tunnel-autopush)
- ⚠️ Mac-Antwort QC: Wenn qwen3.6 Halluzinationen liefert (z.B. erfundene Tool-Namen), Merge-Prompt schärfen und nochmal laufen lassen — NICHT in Cloud "kurz nachbessern"
- ⚠️ Cloudflare-Free killt Mac-Requests >100s → bei langen Merges `stream:true` nutzen

## Quick-Commands

| Situation | Nächster Schritt |
|---|---|
| User pastet ZIP-File ohne Kontext | „Was möchtest du damit machen — Skill ersetzen, mergen oder anschauen?" |
| User schreibt „check mal das File" | ZIP-Struktur listen, gleichnamigen installierten Skill suchen, **Mac-Subagent** für Vergleichstabelle |
| Neuer Skill nutzt unbekannte APIs | Translation-Layer im Mac-Merge-Prompt mitgeben + User über Inkompatibilität informieren |
| User sagt „A" / „Hybrid" | Workflow ab Schritt 6 (Mac-Subagent für Merge) |
| User sagt „B" / „ersetzen" | Vorher Mac-Subagent prüfen lassen ob Tools existieren, dann replace |
| User sagt „C" / „nur Referenz" | Support-File-only Update-Proposal (kurze Mac-Session für Refinement) |
| Skill existiert noch nicht | Wechsel zu `skill_workshop action=create`, **kein** Merge nötig |
| Mac offline | Healthcheck prüfen → LM Studio als Fallback → bei beidem offline User fragen |

## Token-Ökonomie

Dieser Skill spart Cloud-Tokens **systematisch**:

- Skill-Material-Analyse (~2-5K Token Input): Mac statt Cloud
- Hybrid-SKILL.md-Generierung (~3-8K Token Output): Mac statt Cloud
- Reference-Datei-Extraktion (~2-5K Token): Mac statt Cloud
- **Geschätzte Ersparnis pro Merge:** 10-20K Cloud-Token = realer €-Betrag

Hauptassistent (Cloud) macht nur noch:
- User-Dialog & Optionen-Frage
- `read`/`write`/`skill_workshop`-Tool-Calls (lokal, billig)
- Endvalidierung der Mac-Outputs
