Diseño de especificaciones de entrada/salida de Skills

Un buen Skill no solo debe completar la tarea, sino también definir claramente "qué acepta" y "qué produce".

Una buena especificación de entrada y salida es la base para el funcionamiento confiable de un Skill.

¿Por qué definir especificaciones de entrada y salida?

Los Skills enfrentan solicitudes reales de los usuarios, y los formatos de entrada son muy diversos.

Sin una especificación clara, Claude adivinará la intención de la entrada, lo que provoca un comportamiento inestable.

La especificación no es una limitación, sino que le da a Claude límites de acción claros, reduce la ambigüedad y mejora la consistencia de la salida.

Los cuatro elementos de las especificaciones de entrada

Elemento Descripción Ejemplo
Tipo de entrada Archivo, texto, URL, parámetros, etc. Archivo PDF subido por el usuario
Requisitos de formato Extensión del archivo, codificación, estructura .csv, codificación UTF-8, primera fila como encabezado
Obligatorio/Opcional Qué entradas son obligatorias Ruta del archivo obligatoria, nombres de columnas opcionales
Comportamiento predeterminado Cómo manejar los parámetros opcionales cuando no se proporcionan Analizar todas las columnas cuando no se especifican nombres de columnas

Definir las especificaciones de entrada en SKILL.md

Ejemplo

## Especificaciones de entrada

### Entradas obligatorias

- **Archivo de datos**: el archivo subido por el`.csv`o`.xlsx`archivo
- Codificación: UTF-8(CSV) o formato Excel estándar
- La primera fila debe ser el título de las columnas
- El tamaño del archivo no debe superar los 50 MB

### Entradas opcionales

- **Columna objetivo**: especifica qué columnas analizar; por defecto, analiza todas las columnas numéricas
- **Formato de salida**：`table`(tabla) o`text`(resumen de texto), por defecto`table`
- **Precisión**: número de decimales a conservar, por defecto2Posición

### Manejo de entradas faltantes

Si el archivo no se ha subido, informe al usuario:"Por favor, suba el archivo CSV o Excel que desea analizar."
Si el formato del archivo no es compatible, informe al usuario y enumere la lista de formatos compatibles.

Las tres dimensiones de las especificaciones de salida

Dimensión 1: Contenido de salida

Especificar claramente qué contenido se va a generar, evitando omisiones o salidas excesivas.

Ejemplo

## Contenido de salida

Una vez completado el análisis, proporcione lo siguiente:

1. **Tabla de resumen estadístico**: número de filas por columna, media, máximo/mínimo, cantidad de valores nulos
2. **Informe de calidad de datos**: enumere los problemas encontrados (por ejemplo, demasiados valores nulos, tipos de datos inconsistentes)
3. **Ruta del archivo**: si se generó un archivo de salida, proporcione la ruta de descarga

Dimensión 2: Formato de salida

Especifica el formato en que se presenta la salida y dónde se almacena.

Destino de salida Formato Ruta de almacenamiento
Mostrar en el diálogo Tabla Markdown, bloque de código Sin necesidad de almacenamiento
Archivo descargable .xlsx、.pdf、.html /mnt/user-data/outputs/
Resultado intermedio JSON、CSV /home/claude/(temporal)

Dimensión 3: Momento de salida

Especifica cuándo generar la salida, si se produce todo de una vez o se muestra gradualmente paso a paso.

Ejemplo

## Momento de salida

1. **Después de leer el archivo**: informe inmediatamente al usuario la información básica del archivo (número de filas, columnas, tamaño)
2. **Durante el análisis**: si el análisis tarda más de10segundos, muestre primero un aviso de progreso
3. **Una vez completado el análisis**: genere el resumen estadístico completo
4. **Después de generar el archivo**: muestre la ruta del archivo y llame a la herramienta present_files

Ejemplo completo de especificaciones de entrada y salida

A continuación se muestra la especificación completa de entrada y salida de un Skill de resumen de documentos:

Ejemplo

---
name: doc-summarizer
description: >
Extrae resúmenes de documentos subidos por el usuario, compatible con PDF, Word (.docx) y texto plano.
Se utiliza cuando el usuario necesita comprender rápidamente el contenido de un documento, extraer información clave o generar un resumen del documento.
---

# Resumidor de documentos

## Especificaciones de entrada

### Obligatorio
- Archivo de documento (.pdf, .docx o .txt)

### Opcional
- **Longitud del resumen**：`short`（3oraciones)/ `medium`（1párrafos)/ `long`（3párrafos), por defecto`medium`
- **Idioma**: idioma de salida, por defecto el mismo que el del texto original
- **Áreas de enfoque**: por ejemplo"Enfocarse principalmente en la sección de conclusiones"、"Extraer datos numéricos"

### Manejo de excepciones
- Archivo de más de 10 MB: informe al usuario que el archivo es demasiado grande y sugiera dividirlo antes de subirlo
- Formato no compatible: enumere los formatos compatibles y pida al usuario que vuelva a subir el archivo
- El documento es un escaneo de imagen y no se puede reconocer el texto: informe que no se puede procesar y sugiera usar una herramienta OCR para el preprocesamiento

## Especificaciones de salida

### Contenido de salida (en orden)
1. Información básica del documento: título (si lo hay), número de páginas, estimación de palabras
2. Resumen principal: generar según la longitud especificada por el usuario
3. Palabras clave:5-8palabras clave temáticas

### Formato de salida
- Mostrar todo en el diálogo, utilizando formato Markdown
- No generar archivos adicionales, a menos que el usuario solicite explícitamente guardarlos

### Ejemplo de salida
---
**Documento**：ejemplo-annual-report.pdf（24páginas, aproximadamente12,000 palabras)

**Resumen**: este informe revisa el desempeño anual del negocio de ejemplo, con un crecimiento interanual de usuarios del35%，
la cobertura de documentación técnica aumentó al98%. La estructura de ingresos tiende a diversificarse, con proporciones equilibradas entre ingresos por publicidad y membresías.

**Palabras clave**: informe anual, crecimiento de usuarios, documentación técnica, estructura de ingresos, diversificación
---

Convenciones de entrada y salida a nivel de script

Si el Skill incluye un script, se recomienda usar JSON como formato estructurado de entrada y salida para que Claude pueda analizar los resultados fácilmente.

Ejemplo

# Ruta del archivo: scripts/summarize.py
# Patrón estandarizado de entrada y salida JSON

import json
import sys

def summarize(file_path: str, length: str = "medium") -> dict:
    """
Generar un resumen del documento

Parámetros:
file_path: ruta del documento (obligatorio)
length: longitud del resumen, short/medium/long (opcional, por defecto medium)

Devuelve:
dict, que contiene los campos status, data o error
    """
    try:
        # Simular la lectura del documento
        with open(file_path, "r", encoding="utf-8") as f:
            content = f.read()

        # Simular la generación del resumen
        summary = content[:200] + "..."  # En la práctica, se debe invocar la lógica real de resumen

        return {
            "status": "success",
            "data": {
                "word_count": len(content),
                "summary": summary,
                "length": length
            }
        }

    except FileNotFoundError:
        return {"status": "error", "error": f"El archivo no existe: {file_path}"}
    except Exception as e:
        return {"status": "error", "error": str(e)}

if __name__ == "__main__":
    file_path = sys.argv[1] if len(sys.argv) > 1 else ""
    length    = sys.argv[2] if len(sys.argv) > 2 else "medium"

    result = summarize(file_path, length)

    # Salida JSON unificada para facilitar el análisis de Claude
    print(json.dumps(result, ensure_ascii=False, indent=2))
{
  "status": "success",
  "data": {
    "word_count": 12480,
    "summary": "ejemplo 年度报告回顾了平台在过去一年的业务表现...",
    "length": "medium"
  }
}

Usar JSON como formato de salida del script permite que Claude analice los resultados de manera estable, sin necesidad de interpretar texto libre de forma especulativa.

Otras extensiones