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

## Manejo de errores

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

# Ruta del archivo: scripts/error_handling_demo.py
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

# Ruta del archivo: scripts/auto_install_demo.py
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

# Mensaje de error malo
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"
)
Otras extensiones