Transmisión y recepción de parámetros de Skills

Skills no recibe parámetros explícitos como las funciones tradicionales; percibe la información de entrada a través del contexto de Claude.

Comprender este mecanismo de "transmisión implícita de parámetros" es la clave para escribir un Skill práctico.


Cómo obtiene Skills los parámetros

Cuando Claude lee un Skill, todo el contexto de la conversación son los parámetros de ese Skill.

Esto significa que lo que dice el usuario, los archivos subidos y el historial de la conversación pueden ser fuentes de entrada para el Skill.

Fuente de entrada Ejemplo Descripción
Mensaje actual del usuario "Ayúdame a procesar este PDF" La entrada más directa
Archivo subido El usuario subió report.pdf Se transmite mediante la ruta o el contenido
Historial de la conversación El formato de datos discutido anteriormente Se puede citar en el contexto
Variables del sistema Fecha actual, ruta del directorio de trabajo Claude lo detecta automáticamente

Declarar las entradas esperadas en SKILL.md

En SKILL.md se puede utilizar una descripción en lenguaje natural para indicar a Claude qué información debe extraer del contexto.

A continuación se muestra un ejemplo de Skill para procesar archivos CSV, que demuestra cómo declarar las expectativas de entrada en las instrucciones:

Ejemplo

---
name: csv-analyzer
description: Analizar el archivo CSV subido por el usuario y generar un resumen estadístico. Se activa cuando el usuario menciona CSV o análisis de datos tabulares.
---

# Analizador de CSV

## Requisitos de entrada

El usuario debe proporcionar la siguiente información (obtenida del contexto de la conversación):
- **Ruta del archivo**: la ruta del archivo CSV subido (ubicado en/mnt/user-data/uploads/)
- **Objetivo del análisis**(opcional): qué desea saber el usuario, por ejemplo,"encontrar valores vacíos"、"distribución estadística"
- **Formato de salida**(opcional): tabla, gráfico o resumen de texto

Si la información anterior no está clara, confírmala proactivamente con el usuario antes de ejecutar.

Los "requisitos de entrada" en un Skill están escritos para que Claude los lea. Claude extraerá activamente la información del contexto según estas instrucciones, o preguntará al usuario cuando la información sea insuficiente.


Recibir parámetros estructurados mediante scripts

Cuando un Skill incluye scripts de Python o Shell, los parámetros se pasan mediante argumentos de línea de comandos o entrada estándar.

Esto es exactamente igual que el manejo de parámetros en un script normal.

Ejemplo

# Ruta del archivo: scripts/analyze.py
import argparse
import pandas as pd

def main():
    # Definir los argumentos de línea de comandos
    parser = argparse.ArgumentParser(description="Script de análisis de archivos CSV")
    parser.add_argument("file",        help="Obligatorio: ruta del archivo CSV")
    parser.add_argument("--col",       help="Opcional: especificar el nombre de la columna a analizar")
    parser.add_argument("--limit", type=int, default=10,
                        help="Opcional: número máximo de filas a mostrar, por defecto 10")
    args = parser.parse_args()

    # Leer el archivo
    df = pd.read_csv(args.file)

    # Filtrar columnas según sea necesario
    if args.col:
        df = df[[args.col]]

    # Generar la información estadística
    print(df.head(args.limit).to_string())
    print("\n--- Resumen estadístico ---")
    print(df.describe())

if __name__ == "__main__":
    main()

La forma en que Claude llama a este script en SKILL.md:

Ejemplo

## Ejecutar el análisis

Una vez obtenida la ruta del archivo, ejecuta el siguiente comando:

```bash
python scripts/analyze.py <Ruta del archivo> [--col <Nombre de la columna>] [--limit <Número de filas>]
```

Muestra la salida de la línea de comandos al usuario y proporciona una interpretación en texto.

Normas para el manejo de los parámetros de ruta de archivo

Los archivos subidos por el usuario se encuentran uniformemente en/mnt/user-data/uploads/bajo la ruta.

En los scripts de Skill, utiliza siempre rutas absolutas para acceder a los archivos y evitar errores de resolución de rutas.

Ejemplo

import os

# Correcto: usar ruta absoluta
UPLOAD_DIR = "/mnt/user-data/uploads"
file_path = os.path.join(UPLOAD_DIR, "report.csv")

# Incorrecto: usar ruta relativa (fallará según el directorio de trabajo)
# file_path = "uploads/report.csv"

# Verificar si el archivo existe
if not os.path.exists(file_path):
    print(f"Error: el archivo no existe → {file_path}")
    exit(1)

Validación de parámetros: verificar la entrada antes de ejecutar

Los scripts de Skill deben validar siempre que los parámetros clave sean válidos antes de ejecutarse.

Esto evita fallos en tiempo de ejecución causados por parámetros faltantes o con un formato incorrecto.

Ejemplo

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

def validate_csv_input(file_path: str) -> bool:
    """Verificar si la entrada del archivo CSV es válida"""

    # Verificar si se proporcionó la ruta del archivo
    if not file_path:
        print("Error: no se proporcionó la ruta del archivo")
        return False

    # Verificar si el archivo existe
    if not os.path.exists(file_path):
        print(f"Error: el archivo no existe → {file_path}")
        return False

    # Verificar la extensión del archivo
    if not file_path.lower().endswith(".csv"):
        print(f"Error: tipo de archivo no compatible, se esperaba .csv, actual → {file_path}")
        return False

    # Verificar el tamaño del archivo (advertir si supera los 100 MB)
    size_mb = os.path.getsize(file_path) / (1024 * 1024)
    if size_mb > 100:
        print(f"Advertencia: el archivo es grande ({size_mb:.1f} MB), el procesamiento puede ser lento")

    return True

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Uso: python validate_input.py <ruta_del_archivo>")
        sys.exit(1)

    ok = validate_csv_input(sys.argv[1])
    sys.exit(0 if ok else 1)

Los mensajes de error de la validación de parámetros deben indicar claramente qué se esperaba y qué se obtuvo realmente, para que Claude pueda dar al usuario una explicación específica.

Otras extensiones