Skills Manejo de errores y tolerancia a fallos
Una Skill que solo funciona en condiciones ideales es frágil.
Una Skill robusta debe anticipar errores comunes, ofrecer comentarios claros y recuperarse automáticamente siempre que sea posible.
Tres niveles de manejo de errores
| Nivel | Ubicación | Método de manejo |
|---|---|---|
| Error de validación de entrada | Antes de la ejecución | Verificar la entrada; si no es válida, rechazarla directamente y explicar el motivo |
| Error en tiempo de ejecución | Durante la ejecución del script | Capturar la excepción y generar un mensaje de error estructurado |
| Resultado anómalo | Después de completar la ejecución | Verificar si la salida cumple lo esperado; si no, activar el proceso de corrección |
Definir la estrategia de manejo de errores en SKILL.md
SKILL.md debe incluir una sección clara de manejo de errores que indique a Claude qué hacer cuando encuentre un problema.
Ejemplo
### Problemas de entrada
- Archivo no encontrado: informar al usuario de que la ruta del archivo es incorrecta y pedirle que lo suba de nuevo
- Formato de archivo no compatible: enumerar los formatos admitidos (pdf, docx, txt) y pedir al usuario que lo convierta y vuelva a intentarlo
- Archivo vacío: informar de que el contenido del archivo está vacío y no se puede procesar
### Problemas de ejecución
- Fallo en la ejecución del script: mostrar al usuario el mensaje de error completo, sin ocultarlo
- Dependencia no instalada: intentar primero la instalación automática (pipinstall); si falla, indicar al usuario que la instale manualmente
- Tiempo de espera agotado: si se superan60segundos sin completarse, mostrar el progreso actual y preguntar al usuario si desea seguir esperando
### Problemas de resultados
- Archivo de salida vacío: revisar la lógica de procesamiento y explicar al usuario las posibles causas
- Formato de salida inesperado: mostrar la salida real y preguntar al usuario si está satisfecho
Patrón estándar de manejo de errores en scripts
Los scripts de Python deben usar la estructura try-except y devolver uniformemente un JSON con un campo status.
Ejemplo
import json
import sys
import os
class SkillError(Exception):
"""Clase base de excepción personalizada de Skill"""
def __init__(self, message: str, code: str):
self.message = message
self.code = code # Código de error, para que el programa identifique el tipo de error
super().__init__(message)
class InputError(SkillError):
"""Error de validación de entrada"""
pass
class ProcessError(SkillError):
"""Error en el proceso de manejo"""
pass
def validate_input(file_path: str) -> None:
"""Validar la entrada; lanzar InputError si ocurre un error"""
if not file_path:
raise InputError("No se proporcionó la ruta del archivo", "MISSING_FILE")
if not os.path.exists(file_path):
raise InputError(f"El archivo no existe: {file_path}", "FILE_NOT_FOUND")
if os.path.getsize(file_path) == 0:
raise InputError(f"El contenido del archivo está vacío: {file_path}", "EMPTY_FILE")
def process(file_path: str) -> dict:
"""Lógica principal de procesamiento"""
try:
validate_input(file_path)
with open(file_path, "r", encoding="utf-8") as f:
content = f.read()
# Lógica de procesamiento real (simplificada aquí como conteo de líneas)
lines = content.split("\n")
return {
"status": "success",
"data": {
"file": file_path,
"lines": len(lines),
"chars": len(content)
}
}
except InputError as e:
# Error de entrada: el usuario puede corregirlo y volver a intentarlo
return {
"status": "input_error",
"code": e.code,
"message": e.message,
"hint": "Compruebe si la ruta del archivo es correcta y si el archivo existe y no está vacío"
}
except UnicodeDecodeError:
# Error de codificación: ofrecer una sugerencia concreta de solución
return {
"status": "process_error",
"code": "ENCODING_ERROR",
"message": "La codificación del archivo no es UTF-8 y no se puede leer",
"hint": "Guarde el archivo con codificación UTF-8 y vuelva a intentarlo"
}
except Exception as e:
# Error inesperado: registrarlo por completo para facilitar la depuración
return {
"status": "unexpected_error",
"code": "UNKNOWN",
"message": str(e),
"hint": "Por favor, envíe el mensaje de error anterior al desarrollador"
}
if __name__ == "__main__":
file_path = sys.argv[1] if len(sys.argv) > 1 else ""
result = process(file_path)
print(json.dumps(result, ensure_ascii=False, indent=2))
# 文件存在时的成功输出:
{
"status": "success",
"data": {
"file": "/mnt/user-data/uploads/ejemplo.txt",
"lines": 128,
"chars": 5432
}
}
# 文件不存在时的错误输出:
{
"status": "input_error",
"code": "FILE_NOT_FOUND",
"message": "文件不存在:/mnt/user-data/uploads/missing.txt",
"hint": "请检查文件路径是否正确,文件是否存在且非空"
}
Patrón de tolerancia a fallos con instalación automática de dependencias
Cuando el paquete de Python del que depende el script no está instalado, se puede intentar instalarlo automáticamente dentro del script.
Ejemplo
import subprocess
import sys
def ensure_package(package_name: str, import_name: str = None) -> bool:
"""
Asegurarse de que el paquete de Python esté instalado; si no lo está, instalarlo automáticamente
Parámetros:
package_name: nombre del paquete utilizado con pip para la instalación (p. ej., "python-docx")
import_name: nombre utilizado al importar (p. ej., "docx"); por defecto, igual que package_name
"""
import_name = import_name or package_name
try:
__import__(import_name)
return True # Ya instalado
except ImportError:
print(f"Instalando dependencia: {package_name}...")
result = subprocess.run(
[sys.executable, "-m", "pip", "install", package_name,
"--break-system-packages", "--quiet"],
capture_output=True, text=True
)
if result.returncode == 0:
print(f"Instalación correcta: {package_name}")
return True
else:
print(f"Error en la instalación: {package_name}")
print(result.stderr)
return False
# Ejemplo de uso: asegurarse de que todas las dependencias estén listas al inicio del script
if not ensure_package("pandas"):
sys.exit(1)
if not ensure_package("openpyxl"):
sys.exit(1)
# Una vez que las dependencias estén listas, importar normalmente
import pandas as pd
print("Todas las dependencias están listas, comenzando la ejecución...")
La instalación automática solo es adecuada para entornos de desarrollo y escenarios ligeros. En una Skill de producción, las dependencias deben documentarse e instalarse previamente por el usuario, en lugar de instalarse automáticamente en tiempo de ejecución.
Normas para redactar mensajes de error
Un buen mensaje de error ayuda al usuario a localizar rápidamente el problema; un mal mensaje de error solo causa confusión.
| Dimensión | Mala redacción | Buena redacción |
|---|---|---|
| Describir el problema | "Ocurrió un error" | "El archivo report.csv no existe en el directorio de carga" |
| Explicar el motivo | (Ninguno) | "Puede que el nombre del archivo esté mal escrito o que el archivo aún no se haya subido" |
| Ofrecer una acción | (Ninguno) | "Vuelva a subir el archivo o compruebe si el nombre del archivo es correcto" |
Ejemplo
raise Exception("Error")
# Mensaje de error bueno
raise InputError(
"El archivo ejemplo_data.csv no se encontró en el directorio de carga."
"Posibles causas: el nombre del archivo está mal escrito o el archivo aún no se ha subido."
"Vuelva a subir el archivo e inténtelo de nuevo.",
code="FILE_NOT_FOUND"
)