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 hacerloEjemplo
Correcto: responsabilidad únicapdf-to-text (solo se encarga de extraer texto)
Incorrecto: responsabilidades mezcladaspdf-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

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

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

# Ruta del archivo: scripts/fail_fast.py
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ónPrincipio centralProblema que resuelve
Responsabilidad únicaUn Skill hace una sola cosaActivación inexacta, difícil de mantener
Verificación defensiva de entradasValidación centralizada en la entradaSolo muestra error a mitad de la ejecución
Salida progresivaReportar el progreso por etapasEl usuario no sabe si se está ejecutando
Operaciones idempotentesMisma entrada, misma salidaReintentar produce resultados confusos
Señal clara de finalizaciónNotificar el estado final al completarseEl usuario no sabe si la tarea ha terminado
Declaración de compatibilidad de versionesDeclarar el entorno de ejecución compatibleComportamiento anormal cuando el entorno no coincide
Fail FastDetenerse inmediatamente ante un errorContinuar con el error y producir salidas no válidas
Otras extensiones