Skills- und Toolchain-Integration

Durch die Integration mit externen Toolchains können Skills Aufgaben erledigen, die Claude allein nicht bewältigen kann.

Dieser Artikel zeigt, wie man in einem Skill Kommandozeilentools, Systemtools und Drittanbieterbibliotheken aufruft, und enthält ein vollständiges Integrationsbeispiel.


Tooltypen, die Skills aufrufen können

Tool-TypBeispielAufrufmethode
Systembefehlels、cp、find、wcsubprocess.run()
Sprachlaufzeitpython、node、bashsubprocess.run()
Dokumentenverarbeitungswerkzeugepandoc、pdflatexsubprocess.run()
Medienverarbeitungswerkzeugeffmpeg、imagemagicksubprocess.run()
Python-Bibliothekenpandas、openpyxl、pypdfDirekt nach dem Import aufrufen
Node.js-Toolsprettier, eslintÜber npx aufrufen

Bevor externe Tools aufgerufen werden, prüfen, ob die Tools in der Laufzeitumgebung installiert sind. Gängige Tools (python3, pip, node, npm) sind in der Claude-Sandbox vorinstalliert, aber pandoc, ffmpeg usw. müssen separat installiert werden.


Externe Befehle in Skripten aufrufen

Pythonssubprocess`subprocess`-Modul ist der Standardweg, um externe Befehle aufzurufen. Es wird empfohlen, es einheitlich in wiederverwendbare Hilfsfunktionen zu verpacken.

Beispiel

# Dateipfad: scripts/tool_integration.py
import subprocess
import sys
import json

def run_command(cmd: list, timeout: int = 60) -> dict:
    """
Externen Befehl ausführen und die Ausgabe erfassen

Parameter:
cmd: Befehlsliste, z. B. ["pandoc", "--version"]
timeout: Timeout in Sekunden, Standard 60

Rückgabe:
ein dict, das success, stdout, stderr, returncode enthält
    """

    try:
        result = subprocess.run(
            cmd,
            capture_output=True,   # Sowohl stdout als auch stderr erfassen
            text=True,             # Als String zurückgeben, nicht als Bytes
            timeout=timeout
        )
        return {
            "success": result.returncode == 0,
            "returncode": result.returncode,
            "stdout": result.stdout.strip(),
            "stderr": result.stderr.strip()
        }
    except FileNotFoundError:
        return {
            "success":    False,
            "returncode": -1,
            "stdout":     "",
            "stderr":     f"Befehl nicht gefunden: {cmd
        }
    except subprocess.TimeoutExpired:
        return {
            "success":    False,
            "returncode": -1,
            "stdout":     "",
            "stderr":     f"Zeitüberschreitung bei der Befehlsausführung ({timeout} Sekunden überschritten)"
        }

# Beispiel: Verwende pandoc, um Markdown in HTML zu konvertieren
if __name__ == "__main__":
    result = run_command([
        "pandoc",
        "/mnt/user-data/uploads/readme.md",
        "-o", "/mnt/user-data/outputs/readme.html",
        "--standalone"
    ])
    if result["success"]:
        print("Konvertierung erfolgreich")
    else:
        print(f"Konvertierung fehlgeschlagen: {result['stderr']}")
        sys.exit(1)

Prüfen, ob ein Tool verfügbar ist

Die Prüfung, ob die erforderlichen Tools installiert sind, bevor ein Skill ausgeführt wird, liefert klares Feedback, bevor die Aufgabe mittendrin fehlschlägt.

Beispiel

# Dateipfad: scripts/check_tools.py
import shutil
import sys

REQUIRED_TOOLS = [
    ("pandoc",  "sudo apt-get install pandoc"),
    ("ffmpeg",  "sudo apt-get install ffmpeg"),
    ("convert", "sudo apt-get install imagemagick"),
]

def check_tools(tools: list) -> bool:
    """Prüfe die Tool-Liste, gib True zurück, wenn alle bereit sind"""
    all_ok = True
    for tool, install_cmd in tools:
        path = shutil.which(tool)   # Finde den Tool-Pfad in PATH
        if path:
            print(f" Installiert: {tool} → {path}")
        else:
            print(f" Nicht installiert: {tool} Installationsbefehl: {install_cmd}")
            all_ok = False
    return all_ok

if __name__ == "__main__":
    print("Überprüfe Tool-Abhängigkeiten...")
    if not check_tools(REQUIRED_TOOLS):
        print("\n"Bitte installiere zuerst die fehlenden Tools.")
        sys.exit(1)
    print("\n"Alle Tools sind bereit, fahre mit der Ausführung fort.")
检查工具依赖...
  已安装:pandoc → /usr/bin/pandoc
  未安装:ffmpeg  安装命令:sudo apt-get install ffmpeg
  未安装:convert  安装命令:sudo apt-get install imagemagick

请先安装缺少的工具。

Tool-Abhängigkeiten in SKILL.md deklarieren

Verwende dascompatibility`dependencies`-Feld des YAML-Frontmatters, um alle externen Abhängigkeiten aufzulisten, damit Benutzer wissen, was sie vor der Installation des Skills vorbereiten müssen.

---
name: doc-converter
description: >
  将文档在不同格式间转换,支持 Markdown、HTML、PDF、Word。
  当用户需要格式转换、导出文档时触发。
compatibility:
  tools:
    - pandoc >= 2.14   # 文档格式转换
    - python >= 3.8    # 运行辅助脚本
  python_packages:
    - pypdf >= 3.0     # PDF 处理
    - python-docx >= 1.0
---

Node.js-Tools integrieren

Übernpx`npx` kannst du CLI-Tools direkt aus npm-Paketen aufrufen, ohne globale Installation.

Beispiel

# Dateipfad: scripts/use_node_tool.py
import subprocess
import sys

def run_prettier(file_path: str) -> bool:
    """Code-Dateien mit prettier formatieren"""
    result = subprocess.run(
        ["npx", "--yes", "prettier", "--write", file_path],
        capture_output=True,
        text=True
    )
    if result.returncode == 0:
        print(f"Formatierung erfolgreich: {file_path}")
        return True
    print(f"Formatierung fehlgeschlagen: {result.stderr}")
    return False

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Verwendung: python use_node_tool.py <Dateipfad>")
        sys.exit(1)
    sys.exit(0 if run_prettier(sys.argv[1]) else 1)

npx --yesBeim ersten Ausführen wird das Tool-Paket automatisch heruntergeladen, wobei eine Netzwerkverbindung zur npm-Registry erforderlich ist. In netzwerkbeschränkten Umgebungen installieren Sie es vorab global:npm install -g prettier。


Standardisierung von Tool-Aufruf-Ergebnissen

Verschiedene Tools haben unterschiedliche Ausgabeformate. Es wird empfohlen, sie auf der Skill-Ebene einheitlich zu kapseln und nach außen nur eine konsistente Struktur bereitzustellen.

BehandlungsmethodeAnwendungsfallTypische Tools
stdout erfassenDas Tool gibt das Ergebnis an die Standardausgabe auspandoc、wc、cat
Rückgabecode prüfenDas Tool gibt bei Erfolg 0 und bei Fehler einen Wert ungleich null zurückFast alle CLI-Tools
Ausgabedatei lesenDas Tool schreibt das Ergebnis in eine angegebene Dateiffmpeg、pandoc -o
JSON-Ausgabe parsenDas Tool unterstützt den --json-Parametereslint --format json

Vollständiges Integrationsbeispiel: Markdown-zu-PDF-Bericht

Das folgende Beispiel kombiniert pandoc mit einem Python-Skript, um ein vollständiges Skill-Skript zur Markdown-→-PDF-Generierung zu implementieren.

Beispiel

# Dateipfad: scripts/md_to_pdf.py
# Vollständiger Workflow: Tool prüfen → Eingabe validieren → pandoc aufrufen → Ausgabe bestätigen

import subprocess
import shutil
import sys
import os
import json
from datetime import datetime

def check_pandoc() -> bool:
    """Prüft, ob pandoc verfügbar ist"""
    if not shutil.which("pandoc"):
        print("Fehler: pandoc nicht gefunden, bitte ausführen: sudo apt-get install pandoc")
        return False
    return True

def validate_input(md_path: str) -> bool:
    """Validiert die eingegebene Markdown-Datei"""
    if not os.path.exists(md_path):
        print(f"Fehler: Datei existiert nicht → {md_path}")
        return False
    if not md_path.lower().endswith(".md"):
        print(f"Fehler: Datei muss im .md-Format vorliegen → {md_path}")
        return False
    return True

def convert_to_pdf(md_path: str, output_dir: str) -> dict:
    """pandoc aufrufen, um Markdown in PDF zu konvertieren"""
    os.makedirs(output_dir, exist_ok=True)

    # Einen Ausgabedateinamen mit Zeitstempel generieren, um das Überschreiben alter Dateien zu vermeiden
    base_name   = os.path.splitext(os.path.basename(md_path))[0]
    timestamp   = datetime.now().strftime("%Y%m%d_%H%M%S")
    output_path = os.path.join(output_dir, f"{base_name}_{timestamp}.pdf")

    result = subprocess.run(
        [
            "pandoc", md_path,
            "-o", output_path,
            "--pdf-engine=xelatex",      # Chinesisch unterstützen
            "-V", "CJKmainfont=SimSun",  # Chinesische Schriftart (je nach Umgebung anpassen)
            "-V", "geometry:margin=2cm"  # Seitenrand
        ],
        capture_output=True,
        text=True,
        timeout=120
    )

    if result.returncode == 0 and os.path.exists(output_path):
        size_kb = os.path.getsize(output_path) // 1024
        return {
            "status":  "success",
            "output": output_path,
            "size_kb": size_kb
        }
    return {
        "status": "error",
        "message": result.stderr or "pandoc hat keine Ausgabedatei erzeugt"
    }

def main():
    if len(sys.argv) < 2:
        print("Verwendung: python md_to_pdf.py <Markdown-Dateipfad>")
        sys.exit(1)

    md_path    = sys.argv[1]
    output_dir = "/mnt/user-data/outputs"

    # Schritt für Schritt prüfen; sofort beenden, wenn ein Schritt fehlschlägt
    if not check_pandoc():
        sys.exit(1)
    if not validate_input(md_path):
        sys.exit(1)

    print(f"Konvertiere: {md_path}")
    result = convert_to_pdf(md_path, output_dir)
    print(json.dumps(result, ensure_ascii=False, indent=2))

    sys.exit(0 if result["status"] == "success" else 1)

if __name__ == "__main__":
    main()
正在转换:/mnt/user-data/uploads/example_report.md
{
  "status": "success",
  "output": "/mnt/user-data/outputs/example_report_20260518_102305.pdf",
  "size_kb": 248
}

Rufe dieses Skript in SKILL.md auf:

## 执行转换

获取用户上传的 .md 文件路径后,运行:

```bash
python scripts/md_to_pdf.py <文件路径>
```

解析 JSON 输出:
- status 为 "success":调用 present_files 展示 output 路径的文件
- status 为 "error":将 message 内容展示给用户,说明可能原因
Andere Erweiterungen