Skills: patrones de diseño y mejores prácticas
Los patrones de diseño de Skills, resumidos a partir de una gran cantidad de práctica, te ayudan a tomar decisiones razonables rápidamente ante nuevos requisitos.
Este artículo resume los 7 patrones de diseño más utilizados y sus escenarios de aplicación.
Patrón 1: Skill de responsabilidad única
Cada Skill hace una sola cosa y la hace bien.
Cuanto más enfocada esté la funcionalidad, más precisa será la descripción (description), mayor será la precisión de activación y más fácil será el mantenimiento.
| Cómo hacerlo | Ejemplo |
|---|---|
| Correcto: responsabilidad única | pdf-to-text (solo se encarga de extraer texto) |
| Incorrecto: responsabilidades mezcladas | pdf-tools (leer, convertir, combinar, agregar marca de agua... todo junto) |
Si descubres que la descripción de un Skill necesita ser muy larga para explicar claramente lo que "no hace", normalmente significa que asume demasiadas responsabilidades y debería dividirse.
Patrón 2: Verificación defensiva de entradas
Realiza toda la validación de entradas de forma centralizada en la entrada del script del Skill y solo después de que pase la validación se entra en la lógica de negocio.
Ejemplo
# Patrón: verificación defensiva de entradas: validación centralizada en la entrada, se permite el paso si se supera la validación
import sys
import os
import json
def validate(args) -> list:
"""Valida todas las entradas de forma centralizada y devuelve una lista de errores (una lista vacía significa que todo fue aprobado)"""
errors = []
if not args.file:
errors.append("Falta el parámetro --file")
elif not os.path.exists(args.file):
errors.append(f"El archivo no existe: {args.file}")
elif os.path.getsize(args.file) == 0:
errors.append("El contenido del archivo está vacío")
if args.limit < 1:
errors.append("--limit debe ser mayor que 0")
return errors
def run(args):
"""Entrada de la lógica de negocio, solo se llama después de que la validación sea aprobada"""
# Realizar el procesamiento real...
return {"status": "success", "file": args.file}
if __name__ == "__main__":
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--file", required=False, default="")
parser.add_argument("--limit", type=int, default=100)
args = parser.parse_args()
# 1. Validación centralizada
errors = validate(args)
if errors:
result = {"status": "input_error", "errors": errors}
print(json.dumps(result, ensure_ascii=False))
sys.exit(1)
# 2. Ejecutar la lógica de negocio después de la validación
result = run(args)
print(json.dumps(result, ensure_ascii=False))
Patrón 3: Salida progresiva
Para Skills que tardan más de 5 segundos, se debe informar el progreso por etapas en lugar de hacer que el usuario enfrente una espera silenciosa.
## 执行流程(渐进式输出示例) ### 步骤一:读取文件 运行读取脚本后,立即告知用户: > 已读取文件:ejemplo_data.csv(1,024 行,8 列)正在进行数据清洗... ### 步骤二:数据清洗 清洗完成后,告知用户: > 数据清洗完成:删除重复行 3 条,空值填充 12 处。正在生成报告... ### 步骤三:生成报告 报告生成后,展示下载链接并说明内容: > 报告已生成,包含统计摘要和数据质量评估。
Patrón 4: Operaciones idempotentes
El resultado de ejecución de un Skill debe ser idempotente: con la misma entrada, sin importar cuántas veces se ejecute, la salida debe ser la misma.
Las operaciones no idempotentes (como agregar contenido en cada ejecución) pueden causar confusión cuando el usuario reintenta.
Ejemplo
import os
from datetime import datetime
OUTPUT_DIR = "/mnt/user-data/outputs"
def get_output_path(base_name: str, suffix: str = ".xlsx") -> str:
"""
Generar una ruta de salida determinista
Forma idempotente: sobrescribir el archivo con el mismo nombre en cada ejecución (en lugar de agregar contenido o generar archivos nuevos)
Asegurar que la misma entrada siempre corresponda al mismo archivo de salida
"""
# Opción A: nombre de archivo fijo (la misma entrada siempre sobrescribe)
return os.path.join(OUTPUT_DIR, f"{base_name}_report{suffix}")
# Opción B (marca de tiempo): generar un archivo nuevo cada vez (no idempotente, pero conserva el historial)
# ts = datetime.now().strftime("%Y%m%d_%H%M%S")
# return os.path.join(OUTPUT_DIR, f"{base_name}_{ts}{suffix}")
Patrón 5: Señal clara de finalización
Después de que el Skill termine de ejecutarse, se debe dar una "señal de finalización" clara para que el usuario sepa que la tarea ha terminado y no necesite seguir esperando.
## 任务完成后的输出规范 无论成功还是失败,最后一步必须输出一个明确的状态行: 成功时: > 任务完成:报告已生成,共处理 1,024 行数据,耗时约 3 秒。 失败时: > 任务中断:在"数据清洗"步骤遇到错误(原因:文件编码不是 UTF-8)。 > 建议:将文件另存为 UTF-8 格式后重新上传。
Patrón 6: Declaración de compatibilidad de versiones
Declara las versiones de modelo compatibles en el frontmatter de SKILL.md para evitar comportamientos inesperados en entornos no compatibles.
---
name: data-analyzer
version: 1.2.0
description: 分析 CSV/Excel 数据,生成统计报告。
compatibility:
claude_models:
- claude-sonnet-4-20250514 # 经过验证的模型版本
- claude-opus-4 # 同样支持
python: ">=3.8"
platforms:
- linux # Claude 计算机使用环境
---
Patrón 7: Fail Fast (fallo rápido)
En cuanto se detecte un error que impida continuar, detente de inmediato e informa con claridad, en lugar de continuar ejecutándose con el error y producir salidas sin sentido.
Ejemplo
import sys
import json
def assert_condition(condition: bool, message: str, hint: str = ""):
"""Si no se cumplen las condiciones, muestra el error inmediatamente y sale (modo Fail Fast)"""
if not condition:
result = {
"status": "error",
"message": message,
"hint": hint
}
print(json.dumps(result, ensure_ascii=False))
sys.exit(1)
# Realizar todas las comprobaciones previas de forma centralizada al inicio del script
import os
file_path = sys.argv[1] if len(sys.argv) > 1 else ""
assert_condition(bool(file_path),
Falta el parámetro de ruta del archivo,
Uso: python script.py <ruta del archivo>)
assert_condition(os.path.exists(file_path),
fEl archivo no existe: {file_path},
Verifica que la ruta sea correcta o vuelve a subir el archivo)
assert_condition(file_path.endswith(".csv"),
Formato de archivo no compatible, se espera .csv,
fArchivo actual: {file_path})
# Todas las comprobaciones pasaron, ejecutar la lógica real
print(json.dumps({"status": "ok", "file": file_path}))
Tabla de referencia rápida de patrones
| Patrón | Principio central | Problema que resuelve |
|---|---|---|
| Responsabilidad única | Un Skill hace una sola cosa | Activación inexacta, difícil de mantener |
| Verificación defensiva de entradas | Validación centralizada en la entrada | Solo muestra error a mitad de la ejecución |
| Salida progresiva | Reportar el progreso por etapas | El usuario no sabe si se está ejecutando |
| Operaciones idempotentes | Misma entrada, misma salida | Reintentar produce resultados confusos |
| Señal clara de finalización | Notificar el estado final al completarse | El usuario no sabe si la tarea ha terminado |
| Declaración de compatibilidad de versiones | Declarar el entorno de ejecución compatible | Comportamiento anormal cuando el entorno no coincide |
| Fail Fast | Detenerse inmediatamente ante un error | Continuar con el error y producir salidas no válidas |