Integración de Skills con la cadena de herramientas

Al integrarse con cadenas de herramientas externas, los Skills pueden completar tareas que Claude por sí solo no puede realizar.

Este artículo explica cómo llamar a herramientas de línea de comandos, herramientas del sistema y bibliotecas de terceros dentro de un Skill, y proporciona un ejemplo completo de integración.


Tipos de herramientas que pueden llamar los Skills

Tipo de herramientaEjemploMétodo de llamada
Comandos del sistemals、cp、find、wcsubprocess.run()
Runtime de lenguajepython、node、bashsubprocess.run()
Herramientas de procesamiento de documentospandoc、pdflatexsubprocess.run()
Herramientas de procesamiento de mediosffmpeg、imagemagicksubprocess.run()
Bibliotecas de Pythonpandas、openpyxl、pypdfLlamada directa después de `import`
Herramientas de Node.jsprettier、eslintLlamada mediante npx

Antes de llamar a una herramienta externa, confirma que esté instalada en el entorno de ejecución. El sandbox de Claude tiene preinstaladas herramientas comunes (python3, pip, node, npm), pero pandoc, ffmpeg, etc. requieren instalación adicional.


Llamar comandos externos en scripts

El módulo `subprocess` de Pythonsubprocesses la forma estándar de llamar comandos externos; se recomienda encapsularlo de forma unificada en una función de utilidad para reutilizarlo.

Ejemplo

# Ruta del archivo: scripts/tool_integration.py
import subprocess
import sys
import json

def run_command(cmd: list, timeout: int = 60) -> dict:
    """
Ejecutar comando externo y capturar la salida

Parámetros:
cmd: lista de comandos, p. ej. ["pandoc", "--version"]
timeout: tiempo de espera en segundos, por defecto 60

Retorna:
Un diccionario que contiene success, stdout, stderr y returncode
    """

    try:
        result = subprocess.run(
            cmd,
            capture_output=True,   # Captura stdout y stderr al mismo tiempo
            text=True,             # Devuelve como cadena, no como 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":     fEl comando no existe: {cmd
        }
    except subprocess.TimeoutExpired:
        return {
            "success":    False,
            "returncode": -1,
            "stdout":     "",
            "stderr":     fTiempo de espera agotado al ejecutar el comando (más de {timeout} segundos)
        }

# Ejemplo: usar pandoc para convertir Markdown a HTML
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(Conversión exitosa)
    else:
        print(fError de conversión: {result['stderr']})
        sys.exit(1)

Comprobar si las herramientas están disponibles

Comprobar si las herramientas necesarias están instaladas antes de ejecutar el Skill permite dar un aviso claro antes de que la tarea falle a mitad de camino.

Ejemplo

# Ruta del archivo: 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:
    """Comprueba la lista de herramientas; devuelve True si todas están listas"""
    all_ok = True
    for tool, install_cmd in tools:
        path = shutil.which(tool)   # Busca la ruta de la herramienta en PATH
        if path:
            print(fInstalado: {tool} → {path})
        else:
            print(fNo instalado: {tool} Comando de instalación: {install_cmd})
            all_ok = False
    return all_ok

if __name__ == "__main__":
    print(Comprobando dependencias de herramientas...)
    if not check_tools(REQUIRED_TOOLS):
        print("\nPor favor, instala primero las herramientas que faltan.)
        sys.exit(1)
    print("\nTodas las herramientas están listas; continúa con la ejecución.)
检查工具依赖...
  已安装:pandoc → /usr/bin/pandoc
  未安装:ffmpeg  安装命令:sudo apt-get install ffmpeg
  未安装:convert  安装命令:sudo apt-get install imagemagick

请先安装缺少的工具。

Declarar dependencias de herramientas en SKILL.md

Usando el campo `dependencies` del frontmatter YAMLcompatibilityse enumeran todas las dependencias externas, para que el usuario sepa qué debe preparar antes de instalar el Skill.

---
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
---

Integrar herramientas de Node.js

Mediante `npx`npxse pueden llamar directamente las herramientas CLI de los paquetes npm sin necesidad de instalación global.

Ejemplo

# Ruta del archivo: scripts/use_node_tool.py
import subprocess
import sys

def run_prettier(file_path: str) -> bool:
    """Formatea archivos de código con prettier"""
    result = subprocess.run(
        ["npx", "--yes", "prettier", "--write", file_path],
        capture_output=True,
        text=True
    )
    if result.returncode == 0:
        print(fFormateo exitoso: {file_path})
        return True
    print(fError de formateo: {result.stderr})
    return False

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

npx --yesEn la primera ejecución, el paquete de herramientas se descargará automáticamente, lo que requiere conexión de red al registro npm. En entornos con red restringida, se debe instalar globalmente con antelación:npm install -g prettier。


Normalización de los resultados de las llamadas a herramientas

Los formatos de salida de las distintas herramientas varían; se recomienda encapsularlos de forma uniforme en la capa del Skill y exponer hacia el exterior una única estructura coherente.

Método de procesamientoEscenario aplicableHerramienta típica
Capturar stdoutLa herramienta envía el resultado a la salida estándarpandoc、wc、cat
Comprobar el código de retornoLa herramienta devuelve 0 en caso de éxito y un valor distinto de 0 en caso de errorCasi todas las herramientas CLI
Leer el archivo de salidaLa herramienta escribe el resultado en un archivo determinadoffmpeg、pandoc -o
Analizar la salida JSONLa herramienta admite el parámetro --jsoneslint --format json

Ejemplo completo de integración: de Markdown a informe PDF

El siguiente ejemplo combina pandoc con un script de Python para implementar un script de Skill completo que convierte Markdown a PDF.

Ejemplo

# Ruta del archivo: scripts/md_to_pdf.py
# Flujo de trabajo completo: comprobar herramienta → validar entrada → llamar a pandoc → confirmar salida

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

def check_pandoc() -> bool:
    """Comprueba si pandoc está disponible"""
    if not shutil.which("pandoc"):
        print(Error: no se encontró pandoc; ejecuta: sudo apt-get install pandoc)
        return False
    return True

def validate_input(md_path: str) -> bool:
    """Valida el archivo Markdown de entrada"""
    if not os.path.exists(md_path):
        print(fError: el archivo no existe → {md_path})
        return False
    if not md_path.lower().endswith(".md"):
        print(fError: el archivo debe tener formato .md → {md_path})
        return False
    return True

def convert_to_pdf(md_path: str, output_dir: str) -> dict:
    """Llama a pandoc para convertir Markdown a PDF"""
    os.makedirs(output_dir, exist_ok=True)

    # Genera un nombre de archivo de salida con marca de tiempo para evitar sobrescribir archivos antiguos
    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",      # Compatibilidad con chino
            "-V", "CJKmainfont=SimSun",  # Fuente china (ajustar según el entorno)
            "-V", "geometry:margin=2cm"  # Márgenes de página
        ],
        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 no generó el archivo de salida
    }

def main():
    if len(sys.argv) < 2:
        print(Uso: python md_to_pdf.py <ruta del archivo Markdown>)
        sys.exit(1)

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

    # Comprueba paso a paso; si algún paso falla, sale de inmediato
    if not check_pandoc():
        sys.exit(1)
    if not validate_input(md_path):
        sys.exit(1)

    print(fConvirtiendo: {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/ejemplo_report.md
{
  "status": "success",
  "output": "/mnt/user-data/outputs/ejemplo_report_20260518_102305.pdf",
  "size_kb": 248
}

En SKILL.md, llama a este script:

## 执行转换

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

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

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