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
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
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
# 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
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)
Otras extensionesLos 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.