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 herramienta | Ejemplo | Método de llamada |
|---|---|---|
| Comandos del sistema | ls、cp、find、wc | subprocess.run() |
| Runtime de lenguaje | python、node、bash | subprocess.run() |
| Herramientas de procesamiento de documentos | pandoc、pdflatex | subprocess.run() |
| Herramientas de procesamiento de medios | ffmpeg、imagemagick | subprocess.run() |
| Bibliotecas de Python | pandas、openpyxl、pypdf | Llamada directa después de `import` |
| Herramientas de Node.js | prettier、eslint | Llamada 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
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
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
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 procesamiento | Escenario aplicable | Herramienta típica |
|---|---|---|
| Capturar stdout | La herramienta envía el resultado a la salida estándar | pandoc、wc、cat |
| Comprobar el código de retorno | La herramienta devuelve 0 en caso de éxito y un valor distinto de 0 en caso de error | Casi todas las herramientas CLI |
| Leer el archivo de salida | La herramienta escribe el resultado en un archivo determinado | ffmpeg、pandoc -o |
| Analizar la salida JSON | La herramienta admite el parámetro --json | eslint --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
# 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