Skills Diseño de flujos de múltiples pasos

Una tarea simple solo requiere un paso, pero los flujos de trabajo reales suelen implicar múltiples etapas.

Este artículo explica cómo descomponer tareas complejas en pasos claros y organizarlas en un flujo de ejecución confiable en SKILL.md.


¿Por qué definir explícitamente los pasos?

Claude es muy inteligente, pero sin una guía clara de pasos, puede omitir ciertas etapas o ejecutarlas en un orden inconsistente.

Beneficios de los pasos explícitos:

Primero, hace que el comportamiento de Claude sea predecible; segundo, facilita que el usuario entienda lo que está sucediendo; tercero, cuando ocurre un error, es fácil localizar en qué paso falló.


Principios básicos del diseño de pasos

Principio Descripción
Cada paso hace solo una cosa Evita que un paso realice múltiples operaciones no relacionadas a la vez.
Entradas y salidas claras entre pasos La salida del paso anterior es la entrada del siguiente, sin depender de estado implícito.
Proporciona retroalimentación después de cada paso Informa al usuario qué completó este paso y cuál es el siguiente.
Permite interrupción en medio del proceso El usuario puede pausar o modificar parámetros en cualquier paso.

Definir flujos de múltiples pasos en SKILL.md

Ejemplo

---
name: excel-report-generator
description: >
Según los datos sin procesar cargados por el usuario, generar un informe de Excel formateado que incluya limpieza de datos,
generación de gráficos y resumen estadístico, tres etapas. Cuando el usuario necesite informes de datos, salida de Excel,
o estadísticas automatizadas, se activa.
---

# Generador de informes Excel

## Proceso de ejecución

### Paso 1: Leer y validar los datos

1. Verificar si el archivo existe y si el formato es .csv o .xlsx
2. Leer el archivo y mostrar información básica:
- Número total de filas y columnas
- Tipos de datos de cada columna
- Conteo de valores vacíos
3. Si se detectan problemas graves (como archivo vacío o formato no compatible), detenerse e informar al usuario.

**Salida**: Informe de información básica de datos (mostrado en el diálogo)

---

### Paso 2: Limpieza de datos

Ejecutar`scripts/clean_data.py`, realizando:
- Eliminar filas completamente duplicadas
- Rellenar los valores vacíos de las columnas numéricas con0
- Eliminar espacios al inicio y final de las cadenas

Exportar los datos limpios a`/home/claude/cleaned_data.csv`

**Salida**: Informe de limpieza (cuántas filas se eliminaron, cuántos valores se modificaron)

---

### Paso 3: Generar resumen estadístico

Ejecutar`scripts/calc_stats.py`, calculando:
- Media, mediana y desviación estándar de cada columna numérica
- Datos de tendencia agrupados por columna de tiempo (si existe una columna de tiempo)

Exportar a`/home/claude/stats.json`

---

### Paso 4: Generar informe de Excel

Ejecutar`scripts/gen_excel.py`, generando un archivo de Excel que contiene:
- Hoja1: datos originales limpios
- Hoja2: tabla de resumen estadístico
- Hoja3: gráfico de líneas (si existen datos de serie temporal)

Guardar el archivo final en`/mnt/user-data/outputs/report_YYYYMMDD.xlsx`

**Salida**: llamar a present_files para mostrar el archivo y proporcionar un enlace de descarga

---

### Manejo de errores

Cuando falla cualquier paso:
1. Mostrar el mensaje de error completo
2. Explicar las posibles causas
3. Preguntar al usuario si desea omitir el paso actual o modificar parámetros y reintentar

Organización de los scripts de pasos

Cada paso de un flujo de múltiples pasos puede corresponder a un archivo de script independiente, o pueden combinarse en un script principal.

Opción 1: un script por paso (recomendado para flujos complejos)

excel-report-generator/
├── SKILL.md
└── scripts/
    ├── clean_data.py      # 第二步:数据清洗
    ├── calc_stats.py      # 第三步:统计计算
    └── gen_excel.py       # 第四步:生成报告

Opción 2: un único script principal (adecuado para flujos simples)

Ejemplo

# Ruta del archivo: scripts/pipeline.py
# Script principal único, controla qué paso ejecutar mediante el parámetro --step

import argparse
import sys

def step_clean(input_file: str, output_file: str) -> dict:
    """Paso 2: Limpieza de datos"""
    print(f"Limpiando datos: {input_file}")
    # Lógica de limpieza real...
    return {"status": "success", "removed_rows": 3, "fixed_values": 12}

def step_stats(input_file: str, output_file: str) -> dict:
    """Paso 3: Cálculo estadístico"""
    print(f"Calculando estadísticas: {input_file}")
    # Lógica estadística real...
    return {"status": "success", "columns_analyzed": 5}

def step_excel(data_file: str, stats_file: str, output_file: str) -> dict:
    """Paso 4: Generar Excel"""
    print(f"Generando informe de Excel: {output_file}")
    # Lógica de generación real...
    return {"status": "success", "output": output_file}

STEPS = {
    "clean": step_clean,
    "stats": step_stats,
    "excel": step_excel,
}

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--step",   required=True, choices=STEPS.keys(),
                        help="Paso a ejecutar: clean / stats / excel")
    parser.add_argument("--input",  required=True, help="Ruta del archivo de entrada")
    parser.add_argument("--output", required=True, help="Ruta del archivo de salida")
    args = parser.parse_args()

    import json
    result = STEPS[args.step](args.input, args.output)
    print(json.dumps(result, ensure_ascii=False, indent=2))

Llamar a este script en SKILL.md:

Ejemplo

# Paso 2: Limpieza de datos
python scripts/pipeline.py \
  --step clean \
  --input /mnt/user-data/uploads/ejemplo_sales.csv \
  --output /home/claude/cleaned_data.csv

# Paso 3: Cálculo estadístico
python scripts/pipeline.py \
  --step stats \
  --input /home/claude/cleaned_data.csv \
  --output /home/claude/stats.json

Verificación de dependencias entre pasos

Cuando los pasos posteriores dependen de los archivos de salida de los pasos anteriores, se debe verificar que los archivos de dependencia existan antes de ejecutar.

Ejemplo

# Ruta del archivo: scripts/check_deps.py
import os
import sys

def check_step_deps(step_name: str, required_files: list) -> bool:
    """
Verifica si los archivos previos de un paso ya se han generado

Parámetros:
step_name: nombre del paso actual (para mensajes de error)
required_files: lista de rutas de archivos que deben existir

Retorna:
True indica que todas las dependencias están listas, False indica que faltan archivos
    """

    missing = [f for f in required_files if not os.path.exists(f)]

    if missing:
        print(f"Error: a {step_name} le faltan archivos previos:")
        for f in missing:
            print(f"  - {f}")
        print("Complete primero los pasos previos.")
        return False

    return True

# Ejemplo de uso: verificar archivos previos antes de generar el Excel en el paso 4
if __name__ == "__main__":
    deps = [
        "/home/claude/cleaned_data.csv",
        "/home/claude/stats.json"
    ]
    if not check_step_deps("Generar informe de Excel", deps):
        sys.exit(1)
    print("Todos los archivos previos están listos, comenzando a generar el informe...")
错误:生成 Excel 报告 缺少前置文件:
  - /home/claude/stats.json
请先完成前置步骤。

En flujos complejos, las dependencias entre pasos son fáciles de pasar por alto. Una verificación de dependencias explícita puede localizar inmediatamente el eslabón faltante cuando ocurre un error, en lugar de que el problema se revele solo en el último paso.

Otras extensiones