Eigene Tools & Skills bauen – Teil 3 der Serie KI-Agenten in der Praxis

Ein KI-Agent, der nur antwortet, bleibt am Ende ein besserer Chatbot. Erst Werkzeuge machen daraus ein System, das Daten holt, Dateien verändert oder fremde Dienste ansteuert. Genau an dieser Stelle werden die Begriffe aber schnell unsauber: Skill, Tool und Protokoll klingen ähnlich, lösen in der Praxis aber unterschiedliche Probleme. Im dritten Teil der Serie geht es deshalb nicht nur um Definitionen, sondern um die eigentliche Architekturfrage: Auf welcher Ebene gibst du einem Agenten neue Fähigkeiten, ohne dir Wartung, Sicherheitslücken oder Integrationschaos einzubauen? Als Einstieg passen dazu auch Tutorial Teil 1 und die Grundlagen Was sind KI-Agenten?.

Die wichtigste Unterscheidung vorweg: Ein Skill ist nicht automatisch ein ausführbares Tool. In OpenClaw beschreibt ein Skill vor allem, wie der Agent vorhandene Fähigkeiten, Dateien, Skripte oder Tools nutzen soll. In LangChain ist ein Tool meist eine Python-Funktion mit Schema. In MCP stellt ein Server Werkzeuge über ein Protokoll bereit, damit mehrere Clients sie nutzen können.

Auf einen Blick

• OpenClaw Skills: Verzeichnisse mit einer SKILL.md. Darin stehen Voraussetzungen, Aktivierungsregeln und Anweisungen, wie der Agent vorhandene Tools oder Hilfsdateien nutzen soll.
• LangChain Tools: Verwandeln Python-Funktionen per @tool in aufrufbare Agenten-Werkzeuge. Type-Hints, Docstrings und optional Pydantic-Modelle definieren das Schema.
• MCP Tools: Werden von einem MCP-Server angeboten. Clients entdecken sie protokollseitig über tools/list und rufen sie über tools/call auf. Die Parameter werden über JSON Schema beschrieben.

Wenn du nur eine Faustregel mitnehmen willst, dann diese: Skills erklären dem Agenten, wie er etwas tun soll. Tools führen etwas aus. MCP wird interessant, sobald diese Ausführung nicht mehr an einen einzelnen Prozess oder an eine einzige Sprache gebunden sein soll.

Einsatzszenarien für eigene Tools

Vorgefertigte Tools decken Standardszenarien ab. Die eigentliche Stärke eines Agenten zeigt sich aber erst, wenn er die spezifische Business-Logik eines Unternehmens kennt: interne CRM- oder Ticket-APIs, Datenbankabfragen, Compliance-Prüfungen, Reporting-Workflows oder kontrollierte Dateioperationen.

Die wichtigste Designfrage lautet deshalb nicht nur, was der Agent können soll, sondern auf welcher Ebene du diese Fähigkeit verankerst.

• Für Anweisungen, Arbeitsabläufe und lokale Hilfsdateien eignet sich ein Skill.
• Für Python-basierte Agentenlogik eignet sich ein LangChain Tool.
• Für mehrere Clients, mehrere Sprachen oder Prozessgrenzen eignet sich MCP.

Diese Wahl ist nicht akademisch. Wer zu früh alles in Python gießt, verliert schnell Wiederverwendbarkeit. Wer alles in Skills beschreibt, obwohl echte Ausführung fehlt, baut am Ende nur bessere Anweisungen ohne belastbare Schnittstelle.

OpenClaw Skills: Anweisungen für vorhandene Fähigkeiten

OpenClaw verwendet Skills als Markdown-Anleitungen mit Frontmatter. Jeder Skill lebt in einem Verzeichnis mit einer SKILL.md. Die Datei enthält YAML-Frontmatter und danach die eigentliche Arbeitsanweisung für das Modell. OpenClaw folgt dabei der AgentSkills-Idee, ergänzt aber eigene Felder unter metadata.openclaw für Gating und Laufzeitverhalten.

Ein Skill erzeugt aber nicht automatisch einen neuen API-Endpunkt. Wenn der Agent eine externe API aufrufen soll, brauchst du zusätzlich ein vorhandenes Tool, ein Skript, ein Plugin, einen MCP-Server oder eine andere ausführbare Fähigkeit, die der Skill beschreibt.

Minimale Struktur einer SKILL.md

---
name: weather-check
description: Hole aktuelle Wetterdaten für eine Stadt über ein vorhandenes Hilfsskript
metadata: { "openclaw": { "requires": { "env": ["OPENWEATHER_API_KEY"], "bins": ["python3"] }, "primaryEnv": "OPENWEATHER_API_KEY" } }
---

Verwende diesen Skill, wenn aktuelle Wetterdaten für eine Stadt benötigt werden.

## Voraussetzungen

- Die Umgebungsvariable `OPENWEATHER_API_KEY` ist gesetzt.
- Im Skill-Ordner liegt ein Skript unter `{baseDir}/weather.py`.
- `python3` ist verfügbar.

## Verwendung

Führe das Skript so aus:

```bash
python3 {baseDir}/weather.py Berlin metric

Parameter

• city: Stadtname, zum Beispiel Berlin oder Hamburg
• units: optional, metric oder imperial

Rückgabe

Gib Temperatur, Wetterbeschreibung und Luftfeuchtigkeit knapp zurück.

Wichtig ist hier ein Detail, das in Tutorials leicht untergeht: OpenClaw dokumentiert `metadata` im Frontmatter als einzeiliges JSON-Objekt. Genau darüber laufen Gating-Regeln wie `requires.bins`, `requires.env` oder `requires.config`. Ein Skill wird also nicht nur beschrieben, sondern schon beim Laden anhand der Umgebung gefiltert.

### Praktischer Skill mit Hilfsskript

Ein Skill kann ein kleines Skript mitliefern und dem Agenten erklären, wann und wie es zu benutzen ist. Beispiel für einen CSV-Analyse-Skill:

```markdown
---
name: csv-analyzer
description: Analysiere eine CSV-Datei mit Summe, Durchschnitt oder Anzahl
metadata: { "openclaw": { "requires": { "bins": ["python3"] } } }
---

Analysiere eine lokale CSV-Datei mit dem Skript `{baseDir}/csv_stats.py`.

## Verwendung

```bash
python3 {baseDir}/csv_stats.py data.csv revenue sum

Parameter

• filepath: Pfad zur CSV-Datei
• column: Spaltenname
• operation: sum, average oder count

Sicherheitsregeln

• Verwende nur Dateien im erlaubten Workspace.
• Frage nach, wenn der Pfad außerhalb des Projektverzeichnisses liegt.
• Verändere die CSV-Datei nicht.

Dazu ein minimales Skript:

```python
import csv
import sys
from pathlib import Path

ALLOWED_OPERATIONS = {'sum', 'average', 'count'}

if len(sys.argv) != 4:
    raise SystemExit('Usage: python3 csv_stats.py <file> <column> <sum|average|count>')

path = Path(sys.argv[1]).resolve()
column = sys.argv[2]
operation = sys.argv[3]

if operation not in ALLOWED_OPERATIONS:
    raise SystemExit(f'Unsupported operation: {operation}')

if not path.is_file():
    raise SystemExit(f'File not found: {path}')

values = []
with path.open(newline='', encoding='utf-8') as handle:
    reader = csv.DictReader(handle)
    if column not in (reader.fieldnames or []):
        raise SystemExit(f'Column not found: {column}')
    for row in reader:
        raw = row.get(column, '').strip()
        if raw:
            values.append(float(raw))

if operation == 'count':
    print(len(values))
elif operation == 'sum':
    print(sum(values))
else:
    print(sum(values) / len(values) if values else 0)

Woran du Skills in OpenClaw praktisch festmachst

OpenClaw dokumentiert inzwischen ziemlich klar, wo Skills liegen und wie sie geladen werden. Relevant sind vor allem die Workspace-Skills unter skills/, dazu projektbezogene, persönliche und global verwaltete Skill-Roots mit definierter Priorität. Für einen normalen lokalen Skill ist der Einstieg deshalb deutlich einfacher als in älteren Blogposts oft beschrieben.

Sinnvoll ist diese Reihenfolge:

1. Den Skill im Workspace unter skills/<dein-skill>/SKILL.md anlegen.
2. Falls nötig, Hilfsdateien wie Skripte im selben Verzeichnis oder Unterordnern ablegen.
3. Mit openclaw skills list prüfen, ob der Skill erkannt wird.
4. Mit einem ungefährlichen Read-only-Test beginnen.
5. Wenn Änderungen nicht sofort auftauchen, zuerst eine neue Session starten. Erst wenn Watcher oder Session-Kontext im Weg stehen, ist ein Neustart des Gateways nötig.

Im Alltag ist das die eigentliche Erkenntnis: Viele vermeintliche Tool-Probleme sind in Wahrheit schlecht beschriebene Skill-Probleme.

LangChain Tools: Python-Funktionen mit Schema

Im LangChain-Ökosystem macht der @tool-Decorator aus regulären Python-Funktionen Agenten-Werkzeuge. Type-Hints und Beschreibungstexte sind dabei keine Kür, sondern die eigentliche Schnittstelle zum Modell. Aus ihnen entstehen Schema, Parameterbeschreibung und oft auch die Qualität der Tool-Auswahl.

Einfaches Tool mit @tool

from langchain.tools import tool

@tool
def get_weather(city: str, units: str = 'metric') -> str:
    '''Hole aktuelle Wetterdaten für eine Stadt.

    Args:
        city: Stadtname.
        units: metric für Celsius oder imperial für Fahrenheit.
    '''
    return f'22°C in {city}, sonnig'

print(get_weather.invoke({'city': 'Berlin'}))

Für komplexere Eingaben empfiehlt sich ein Pydantic-Schema. Dadurch werden erlaubte Werte, Defaults und Beschreibungen expliziter.

Erweitertes Tool mit Pydantic-Schema

from pydantic import BaseModel, Field
from langchain.tools import tool

class WeatherInput(BaseModel):
    '''Input für Wetter-Abfragen.'''

    city: str = Field(description='Stadtname oder Koordinaten')
    units: str = Field(default='metric', description='metric oder imperial')
    include_forecast: bool = Field(default=False, description='5-Tage-Vorhersage einbeziehen')

@tool(args_schema=WeatherInput)
def get_weather_advanced(city: str, units: str = 'metric', include_forecast: bool = False) -> str:
    '''Hole detaillierte Wetterdaten.'''
    forecast = ' inklusive Vorhersage' if include_forecast else ''
    return f'Wetter in {city}: 22°C, units={units}{forecast}'

Wenn das Tool auf Kontext, Store oder Langzeit-Speicher zugreifen muss, kommt ToolRuntime ins Spiel.

Kontext-Zugriff mit ToolRuntime

from langchain.tools import ToolRuntime, tool

@tool
def get_user_balance(account_id: str, runtime: ToolRuntime) -> str:
    '''Hole den gespeicherten Kontostand für einen Nutzer.'''
    user_id = runtime.context.user_id
    store = runtime.store
    balance = store.get(('balances', user_id), account_id)
    return f'Kontostand: {balance.value if balance else "Nicht gefunden"}'

Achte darauf, dass die Importpfade und Runtime-Helfer zur installierten LangChain-Version passen. Gerade bei schnell rotierenden Python-Stacks ist das oft die Stelle, an der ein scheinbar einfaches Tutorial in der Praxis zuerst knackt.

MCP: Tools über ein Protokoll bereitstellen

Das Model Context Protocol trennt den Tool-Provider, also den Server, von der LLM-Anwendung als Client. Das ist sinnvoll, wenn mehrere Clients dieselben Werkzeuge nutzen sollen oder wenn Tool-Logik bewusst außerhalb des Agentenprozesses laufen muss.

Ein MCP-Tool wird mit Name, Beschreibung und inputSchema beschrieben. Clients entdecken verfügbare Tools protokollseitig über tools/list und rufen sie über tools/call auf.

MCP Tool-Definition

{
  "name": "github_create_issue",
  "description": "Erstelle ein GitHub-Issue",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "body": { "type": "string" },
      "labels": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["title"]
  }
}

Bei MCP ist strikte Validierung besonders wichtig, weil Server und Client getrennt sind. Der Server sollte alle Parameter gegen das Schema prüfen, Berechtigungen serverseitig erzwingen und Tool-Aufrufe auditierbar loggen. Fachliche Fehler sollten als Tool-Ergebnis zurückgegeben werden, statt den Transport unnötig abbrechen zu lassen.

Entscheidungsmatrix

Kriterium	OpenClaw Skills	LangChain Tools	MCP Tools
Einbindung	OpenClaw-spezifisch	LangChain/LangGraph-spezifisch	Protokoll-basiert
Primärer Zweck	Agent anleiten	Python-Funktion aufrufbar machen	Tool-Server bereitstellen
Ausführung	Über vorhandene Tools, Skripte oder Plugins	In Python-Agentenruntime	Im MCP-Server
Schema	YAML-Frontmatter plus Textanweisung	Type-Hints/Pydantic	JSON Schema
Kontext-Zugriff	Abhängig von OpenClaw-Fähigkeiten	Über Runtime, Context und Store	Serverseitig
Distribution	Skill-Verzeichnis und konfigurierten Skill-Root	Python-Package oder App-Code	MCP-Server
Geeignet für	Arbeitsanweisungen und lokale Agentenfähigkeiten	Python-native Agenten	Multi-Client-Integrationen

Die Wahl hängt stark von der bestehenden Infrastruktur ab. OpenClaw Skills eignen sich, wenn ein Agent klare lokale Arbeitsanweisungen und Voraussetzungen bekommen soll. Wer tief im LangChain- oder LangGraph-Ökosystem arbeitet und State-Management in Python benötigt, nutzt native LangChain Tools. MCP spielt seine Stärken aus, wenn Tools unabhängig vom einzelnen Client bereitgestellt werden sollen.

Best Practices für Tool-Entwicklung

Unabhängig vom Framework gelten einige Regeln:

• Atomare Operationen: Ein Tool erfüllt genau eine Aufgabe, etwa create_user statt manage_user.
• Read-only zuerst: Starte mit ungefährlichen Leseoperationen, bevor du Schreibzugriffe erlaubst.
• Explizite Schemas: Parameter, Defaults und erlaubte Werte müssen maschinenlesbar beschrieben sein.
• Sprechende Fehler: Das Modell braucht konkrete Hinweise wie API-Schlüssel ungültig oder Datei nicht gefunden.
• Least Privilege: API-Schlüssel, Dateirechte und Datenbanknutzer sollten nur die nötigen Rechte haben.
• Pfadvalidierung: Dateitools müssen Workspace-Grenzen, Symlinks und Pfad-Traversal beachten.
• Idempotenz: Write-Tools sollten doppelte Aufrufe erkennen oder sicher wiederholbar sein.
• Audit-Logging: Schreibende oder externe Aktionen sollten nachvollziehbar protokolliert werden.
• Rate-Limits und Timeouts: Agenten können Tools häufiger aufrufen als erwartet.
• Human Approval: Riskante Aktionen wie Löschen, Kaufen, Versenden oder Deployen brauchen Freigaben.

Integration in der Praxis

Der Einstieg gelingt iterativ. Beginne mit Read-only-Tools wie Wetter-APIs, Suchabfragen oder Datenbank-Lookups. Danach folgen begrenzte Write-Operationen wie Exportjobs oder klar validierte POST-Requests. Erst wenn diese stabil laufen, solltest du zustandsbehaftete Tools für Session-Management oder Multi-Step-Workflows einführen.

Die höchste Komplexität beginnt dort, wo mehrere Ebenen gleichzeitig zusammenspielen: ein Skill beschreibt den Ablauf, ein Tool führt die Operation aus und ein Protokoll wie MCP macht dieselbe Fähigkeit für mehrere Clients nutzbar. Bricht an dieser Stelle eine Annahme, liegt der Fehler selten nur im Code. Dann fehlen meistens klare Zuständigkeiten, enge Rechte oder eine Schnittstelle, die das Modell zuverlässig verstehen kann.

Worauf es in der Praxis ankommt

Werkzeuge übersetzen die analytischen Fähigkeiten eines KI-Agenten in messbaren Nutzen. Die entscheidende Frage ist deshalb nicht, ob du eine Fähigkeit irgendwo unterbringst, sondern auf welcher Ebene sie sauber kontrollierbar bleibt.

Für lokale Arbeitsweisen und bestehende Hilfsdateien reicht oft ein Skill. Für Python-native Agentenlogik ist ein LangChain Tool meist direkter. Wenn mehrere Clients, Sprachen oder Prozessgrenzen ins Spiel kommen, wird MCP zur robusteren Schnittstelle. Wer diese Entscheidung bewusst trifft, baut Agenten, die nicht nur mehr können, sondern deren Fähigkeiten auch prüfbar, sicher und wartbar bleiben. Im vierten Teil der Serie geht es darum, wie solche Tools in robusten Multi-Agenten-Systemen orchestriert werden.