Depuración de Skills

Después de escribir un Skill, es habitual encontrarse con problemas como "no se activa", "error de ejecución" o "salida incorrecta".

Este artículo presenta las ideas y métodos básicos para diagnosticar estos problemas.

Tres tipos comunes de problemas de depuración

Tipo de problema Síntoma Punto de revisión prioritario
No se activa Claude no usa el Skill en absoluto Redacción de description, complejidad de la tarea
Se activa pero falla la ejecución El Skill se lee, pero el script falla al ejecutarse Ruta del script, dependencias, formato de parámetros
Se activa y se ejecuta, pero el resultado no coincide con lo esperado El contenido de salida difiere de lo esperado Claridad de las instrucciones en SKILL.md

Problema de depuración 1: el Skill no se activa

Este es el problema más común. Los pasos para diagnosticarlo son:

Primer paso: confirmar que el archivo Skill se cargó correctamente

Ejemplo

# Verificar si la estructura de directorios del Skill es correcta
ls -la my-skill/

# Confirmar que SKILL.md existe y no está vacío
wc -l my-skill/SKILL.md
-rw-r--r-- 1 user user  842 May 18 10:00 SKILL.md

Segundo paso: verificar el formato del frontmatter YAML

Un formato incorrecto del frontmatter hará que el Skill no sea reconocido.

---
name: my-skill
description: 这是一个示例 Skill，处理用户上传的文本文件。
---

# My Skill
...

El frontmatter debe---comenzar y terminar,nameydescriptionLos nombres de campo no pueden tener espacios adicionales; debe haber un espacio después de los dos puntos.

Tercer paso: usar mensajes de prueba más complejos

Las tareas simples (como "leer este archivo") pueden no activar el Skill.

Cambia el mensaje de prueba por una solicitud compleja de varios pasos con requisitos claros de formato de salida.

Mensajes difíciles de activar Mensajes más fáciles de activar
"Analiza este archivo" "Analiza este CSV de datos de ventas, identifica la tendencia de crecimiento mensual y genera una tabla resumen estadística"
"Genera un PPT" "Según este informe, crea una presentación de producto de 10 páginas que incluya gráficos y un resumen"

Problema de depuración 2: error de ejecución del script

Cuando el script falla, el mensaje de error aparece en la salida de la línea de comandos.

En una sesión de Claude, puedes pedirle directamente a Claude que ejecute el script y revise la salida:

Ejemplo

# Ejecutar el script manualmente y revisar la salida de errores
python scripts/process.py /mnt/user-data/uploads/test.csv

# Añadir el parámetro -v (verbose) para ver los registros detallados (si el script lo admite)
python scripts/process.py /mnt/user-data/uploads/test.csv --verbose

Tipos de errores comunes y métodos de corrección

Mensaje de error Causa Método de corrección
ModuleNotFoundError: No module named 'pandas' Dependencia no instalada Ejecutarpip install pandas --break-system-packages
FileNotFoundError: [Errno 2] Ruta de archivo incorrecta Comprobar si el archivo está en/mnt/user-data/uploads/
PermissionError: [Errno 13] Sin permiso de escritura Cambiar el destino de salida a/mnt/user-data/outputs/
SyntaxError Error de sintaxis en el script usarpython -m py_compile 脚本名.pyComprobar

Verificación rápida de sintaxis

Ejemplo

# Verificar la sintaxis del script de Python (sin ejecutarlo, solo validar la sintaxis)
python -m py_compile scripts/process.py && echo "Sintaxis correcta" || echo "Error de sintaxis"

# Verificar la sintaxis del script de Shell
bash -n scripts/run.sh && echo "Sintaxis correcta" || echo "Error de sintaxis"
gramaticalmente correcto

Problema de depuración 3: el resultado de salida no coincide con lo esperado

Este tipo de problema suele deberse a que las instrucciones en SKILL.md no son lo suficientemente claras o son ambiguas.

Método de solución: reducir el alcance paso a paso

Añade temporalmente instrucciones de salida de depuración en SKILL.md para observar cómo entiende Claude cada paso:

## 调试模式（开发时使用，发布前删除）

执行前，先输出以下信息供确认：
1. 识别到的输入文件路径
2. 用户期望的输出格式
3. 计划执行的步骤列表

等待用户确认后再继续执行。

Problemas comunes de ambigüedad en las instrucciones

Redacción ambigua Redacción clara
"Muestra el resultado cuando termines el procesamiento" "Guarda el resultado en el directorio /mnt/user-data/outputs/ y muestra la ruta del archivo en la conversación"
"Analiza los datos" "Calcula la media, la mediana y la desviación estándar de cada columna y muéstralas en una tabla Markdown"
"Genera un informe" "Genera un archivo HTML que contenga un párrafo de resumen, una tabla de datos y una conclusión, y guárdalo en el directorio de salida"

Usar print para depurar dentro del script

Añadir sentencias print en los puntos clave del script es la forma más directa de diagnosticar problemas en el flujo de ejecución.

Ejemplo

# Ruta del archivo: scripts/debug_example.py
import sys

def process_file(file_path: str):
    print(f"[DEBUG] Comenzando a procesar el archivo: {file_path}")  # Punto de depuración 1

    with open(file_path, "r", encoding="utf-8") as f:
        content = f.read()

    print(f"[DEBUG] Archivo leído correctamente, tamaño: {len(content)} bytes")  # Punto de depuración 2

    lines = content.split("\n")
    print(f"[DEBUG] Número total de líneas: {len(lines)}")  # Punto de depuración 3

    # Lógica de procesamiento real
    result = [line.strip() for line in lines if line.strip()]
    print(f"[DEBUG] Líneas válidas después del procesamiento: {len(result)}")  # Punto de depuración 4

    return result

if __name__ == "__main__":
    output = process_file(sys.argv[1])
    print("\n--- Resultado del procesamiento ---")
    for line in output[:5]:  # Mostrar solo las primeras 5 líneas
        print(line)
[DEBUG] 开始处理文件：/mnt/user-data/uploads/sample.txt
[DEBUG] 文件读取成功，大小：1024 字节
[DEBUG] 总行数：32
[DEBUG] 处理后有效行数：28

--- 处理结果 ---
第一行内容
第二行内容
...

Después de terminar la depuración, recuerda eliminar[DEBUG]las sentencias print que comienzan con [DEBUG], para evitar que la información de depuración se mezcle con la salida final.

Otras extensiones