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-Typ | Beispiel | Aufrufmethode |
|---|---|---|
| Systembefehle | ls、cp、find、wc | subprocess.run() |
| Sprachlaufzeit | python、node、bash | subprocess.run() |
| Dokumentenverarbeitungswerkzeuge | pandoc、pdflatex | subprocess.run() |
| Medienverarbeitungswerkzeuge | ffmpeg、imagemagick | subprocess.run() |
| Python-Bibliotheken | pandas、openpyxl、pypdf | Direkt nach dem Import aufrufen |
| Node.js-Tools | prettier, 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
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
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
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.
| Behandlungsmethode | Anwendungsfall | Typische Tools |
|---|---|---|
| stdout erfassen | Das Tool gibt das Ergebnis an die Standardausgabe aus | pandoc、wc、cat |
| Rückgabecode prüfen | Das Tool gibt bei Erfolg 0 und bei Fehler einen Wert ungleich null zurück | Fast alle CLI-Tools |
| Ausgabedatei lesen | Das Tool schreibt das Ergebnis in eine angegebene Datei | ffmpeg、pandoc -o |
| JSON-Ausgabe parsen | Das Tool unterstützt den --json-Parameter | eslint --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
# 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