Agent Skill

Si usas un asistente de programación con IA como Claude Code, Codex o Cursor, el Skill de SpicyAPI le enseña a trabajar con SpicyAPI como es debido. Lo instalas una sola vez. A partir de ahí puedes decirle «añade generación de imágenes con SpicyAPI a mi aplicación» y el asistente seguirá las reglas de SpicyAPI en lugar de improvisar.

No hace falta ser desarrollador para seguir esta página. Si sabes pegar un comando en una terminal, sabes instalar el Skill.

Qué es un Skill

Un Skill es una carpeta de instrucciones escritas para un asistente de IA, no para personas. Piensa en él como el manual de procedimientos que le entregarías a un compañero nuevo: no hace el trabajo por sí mismo, pero le dice a quien lo hace qué pasos seguir, en qué orden y qué no debe hacer nunca.

Los asistentes de IA saben mucho de programación en general, pero no conocen de forma fiable las reglas concretas de SpicyAPI. Si tiene que adivinar, un asistente puede:

• inventarse un ID de modelo o un campo de entrada que no existe;
• pegar tu clave de API directamente en tu código;
• enviar dos veces la misma solicitud de pago después de un corte de red, y pagar dos veces;
• darte un enlace a un resultado que deja de funcionar a los pocos días.

Con el Skill instalado, el asistente lee las reglas de SpicyAPI antes de empezar. En la práctica funciona así:

1. La carpeta del Skill está en un lugar que tu asistente revisa al iniciar una sesión.
2. El asistente lee el resumen de un párrafo del Skill. Cuando tu petición tiene que ver con SpicyAPI, abre las instrucciones completas. No hace falta que menciones el Skill por su nombre.
3. Sigue esas instrucciones mientras escribe código o ejecuta comandos por ti.

Tres datos que conviene saber desde el principio:

• Es solo texto. Archivos Markdown y YAML: ningún programa, ningún script, nada que se ejecute al instalarlo. Puedes abrir cada archivo con un editor de texto; consulta Qué contiene.
• No contiene ninguna clave de API y no hace llamadas. Por sí solo no puede acceder a tu cuenta ni gastar dinero.
• Es gratuito y de código abierto. Tiene licencia MIT, está publicado en npm como @spicyapi/skill y se desarrolla en abierto en github.com/spicyapi-ai/spicy-skill.

Skill, MCP, SDK y CLI

SpicyAPI tiene cuatro herramientas oficiales. Resuelven problemas distintos y están pensadas para usarse juntas.

El Skill no sustituye a ninguna de ellas. Le dice al asistente cómo usarlas: las herramientas MCP cuando están conectadas, la CLI para operaciones puntuales y el SDK de tu lenguaje para el código que va dentro de tu aplicación.

• Solo el Skill. El asistente escribe código de integración correcto para tu proyecto, pero no puede consultar nada de tu cuenta ni ejecutar tareas por ti.
• Solo MCP. El asistente puede actuar sobre tu cuenta, pero cada vez tiene que deducir por su cuenta el orden correcto de los pasos.
• Los dos. El asistente puede probar cosas por ti y las hace de la forma documentada. Si quieres que tu asistente ejecute tareas reales, instala los dos. No entran en conflicto.

En qué te ayuda

La columna de la izquierda es lo que pides. La de la derecha es lo que el Skill hace que el asistente haga mientras te lo entrega.

Lo que no hará

• Gastar dinero por su cuenta. El Skill es texto y no puede llamar a nada. Si tu asistente también tiene el servidor MCP o la CLI y una clave de API, puede crear tareas de pago. El Skill le indica que antes te muestre el precio y obtenga tu confirmación explícita, salvo que tu petición ya autorizara claramente esa ejecución de pago concreta. Con el servidor MCP, además, cada acción de pago se detiene para pedir una confirmación que el asistente no puede saltarse.
• Inventar funciones. No escribirá llamadas a cosas que la API pública no ofrece, como cancelar una tarea, borrar el registro de una tarea o reenviar un webhook.
• Tocar los ajustes de tu cuenta. El registro, el inicio de sesión, los pagos, las recargas de saldo, los miembros del equipo, las solicitudes de privacidad y el cierre de la cuenta se quedan en la consola de SpicyAPI. El asistente no intentará automatizarlos.
• Fingir una prueba. Si le pides una prueba real, hace una solicitud real (y posiblemente de pago, tras tu confirmación) e informa de lo que ocurrió de verdad. Un mock que pasa nunca se presenta como «verificado».
• Añadir un ajuste de contenido. SpicyAPI no tiene ningún indicador de modo de contenido ni revisión del contenido de cada solicitud, y el Skill no se inventa ninguno. El modelo que elijas decide lo que puede hacer.

Antes de empezar

Necesitas cuatro cosas. Para instalar solo hacen falta las tres primeras.

1. Un asistente de programación con IA compatible con Agent Skills. Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf y muchos otros lo son. El Skill usa el formato de carpeta portable de Agent Skills, así que funciona con cualquier asistente que lea ese formato. Si no estás seguro de si el tuyo lo admite, busca «skills» en su documentación.

2. Node.js 22 o posterior, que incluye el comando npx. Compruébalo con:

   node --version

   El instalador skills pide actualmente Node.js 22.20 o posterior, y el instalador propio del paquete necesita 22.13 o posterior. Si no se encuentra el comando o la versión es menor, instala la versión LTS desde nodejs.org y abre una terminal nueva.

3. Una terminal. En macOS, la aplicación Terminal. En Windows, PowerShell. Ejecuta los comandos desde la carpeta de tu proyecto si quieres una instalación por proyecto.

4. Una clave de API de SpicyAPI, cuando empieces a llamar a la API. Para instalar el Skill no hace falta. Crea una clave en la consola; empieza por sk-spicy- y solo se muestra una vez. Guárdala en una variable de entorno llamada SPICY_API_KEY y no pegues nunca la clave en un chat con tu asistente. Consulta Autenticación.

Instalación

Hay dos formas de instalarlo. Las dos colocan los mismos archivos. Usa la primera salvo que tengas un motivo para no hacerlo.

npx skills add spicyapi-ai/spicy-skill

# Claude Code, solo este proyecto
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex, todos los proyectos
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code y Codex, todos los proyectos, sin preguntas
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

Comprueba que funciona

npx skills list      # Skills instalados en el proyecto actual
npx skills list -g   # Skills instalados para todos los proyectos

Ejemplos de peticiones

Pega cualquiera de estas peticiones en tu asistente y ajusta los detalles. Menciona SpicyAPI en la petición para que el asistente sepa que el Skill se aplica.

Si ya sabes qué modelo quieres, copia su ID exacto de la pestaña API de la página del modelo o del catálogo en vivo autenticado (GET /api/v1/models) y ponlo en la petición. Los ejemplos escriben MODEL_ID_FROM_CATALOG donde va ese ID; es un marcador, no un ID real. Si no tienes ninguno, pide al asistente que elija uno del catálogo en vivo. Consulta Catálogo de modelos y esquemas.

Añadir un endpoint de imágenes a una aplicación Next.js

Añade a mi aplicación Next.js una ruta de API del lado del servidor que reciba un prompt de texto, genere una imagen con SpicyAPI usando el modelo MODEL_ID_FROM_CATALOG, espere el resultado y devuelva el enlace a la imagen. Lee la clave de API de SPICY_API_KEY.

En qué hace fijarse el Skill al asistente:

• La clave se queda en tu servidor, en SPICY_API_KEY. Tu página web llama a tu ruta; nunca llama a SpicyAPI con la clave.
• Lee del catálogo en vivo los campos de entrada actuales de ese modelo antes de construir la solicitud.
• Pide primero una cotización exacta y te muestra el costo estimado y el cargo máximo. La solicitud de pago lleva esa cotización confirmada.
• Crea una clave de idempotencia para la generación y la reutiliza si la solicitud agota su tiempo de espera.
• Espera con un plazo límite y después comprueba el state de la tarea: que una espera haya terminado no significa que la generación haya salido bien.

Recibir resultados con un webhook en Express

Añade a mi servidor Express un endpoint de webhook que reciba los resultados de las tareas de SpicyAPI, verifique la firma con SPICY_WEBHOOK_SECRET y guarde en mi base de datos el enlace al resultado.

• Verifica la firma sobre el cuerpo exacto de la solicitud en bruto antes de interpretarlo como JSON.
• Usa el request_id de la entrega para ignorar duplicados, porque el mismo evento puede llegar más de una vez.
• Lee el resultado directamente de un webhook completo y verificado, sin hacer una consulta adicional.

Copiar los videos terminados a tu propio almacenamiento

Cuando una tarea de video de SpicyAPI salga bien, descarga el video, súbelo a mi bucket de S3 y guarda mi propio enlace en lugar del de SpicyAPI.

• Los enlaces a los resultados son temporales y los archivos generados se guardan unos 14 días, así que guarda una copia duradera que controles tú.
• No envía tu clave de API al descargar desde un enlace de resultado.
• Si un enlace ha caducado, vuelve a pedir la misma tarea a SpicyAPI para obtener un enlace nuevo. Nunca crea una tarea nueva solo para conseguir un enlace.

Convertir la foto de un usuario en un video

Permite que los usuarios suban una foto en mi aplicación y la conviertan en un video corto con SpicyAPI.

• Primero sube el archivo a SpicyAPI y pone en la solicitud la dirección spicy:// devuelta, en lugar de pegar el archivo en base64.
• Respeta los límites de subida: 10 MiB para imágenes, y 90 MiB para video MP4 o WebM y para audio MP3 o WAV.
• Una foto que ya está en un enlace HTTPS público se puede pasar directamente, sin subirla.

Gestionar reintentos y saldo insuficiente

Haz que mi integración con SpicyAPI gestione los fallos: que reintente los tiempos de espera de red sin pagar dos veces, que muestre un mensaje claro cuando el saldo de mi cuenta no alcance y que espere más entre intentos cuando me limiten las solicitudes.

• Después de un tiempo de espera agotado, reintenta con la misma clave de idempotencia, para que un reintento no pueda crear una segunda tarea de pago.
• No reintenta un «saldo insuficiente» (código 40201); tu usuario ve un mensaje claro y tú añades saldo en la consola.
• Espera lo que indique Retry-After antes de volver a intentarlo.
• Si la cotización ha caducado o el precio ha cambiado (código 40901), pide una cotización nueva y te vuelve a preguntar, en lugar de saltarse la comprobación del precio.
• Sabe que reintentar una tarea fallida crea una tarea nueva que se puede cobrar otra vez, así que solo lo hace cuando quieres un intento nuevo.

Generar un lote

Genera con SpicyAPI fotos de producto para los 20 artículos de products.csv, como máximo 3 a la vez, y registra el ID de cada tarea.

• SpicyAPI no tiene endpoint de lotes, así que ejecuta un número limitado de solicitudes a la vez.
• Cada elemento recibe su propia clave de idempotencia y su propio precio.
• Anota el ID de cada tarea en cuanto se acepta la tarea.
• Si un elemento agota su tiempo de espera, recupera solo ese elemento y nunca vuelve a enviar el lote entero.

Qué contiene

La carpeta instalada tiene este aspecto:

spicyapi/
├── SKILL.md
├── references/
│   ├── api-workflows.md
│   └── safety.md
└── agents/
    └── openai.yaml

El asistente solo abre los dos archivos de referencia cuando una tarea los necesita, lo que deja libre su memoria de trabajo para tu proyecto. Para leer los archivos antes de instalar, ejecuta npx @spicyapi/skill path: muestra la carpeta donde el paquete los guarda.

El Skill indica al asistente que configure tu código y tus herramientas con estas variables de entorno. El propio Skill no lee ninguna.

Actualizar y desinstalar

Actualizar

El Skill cambia cuando cambia el flujo de trabajo recomendado de SpicyAPI, y las copias instaladas no se actualizan solas. La carpeta instalada no lleva número de versión, así que reinstalar es la forma más sencilla de asegurarte de que tienes la última.

• Si lo instalaste con npx skills add: vuelve a ejecutar el mismo comando, con el mismo ámbito y los mismos asistentes. Sustituye los archivos instalados por lo que el repositorio tenga en ese momento, así que un cambio te llega en cuanto se publica: no hay que esperar nada.

• Si lo instalaste con el instalador del paquete: vuelve a ejecutarlo con --force y el mismo --target. Si añades @latest, npx descarga el paquete más reciente en lugar de reutilizar uno guardado en caché:

  npx @spicyapi/skill@latest install --target ~/.claude/skills/spicyapi --force

Desinstalar

Quitar el Skill no afecta a tu cuenta de SpicyAPI, a tus claves de API ni a ningún código que el asistente ya haya escrito.

• Si lo instalaste con npx skills add: ejecuta esto desde la misma carpeta del proyecto, añadiendo -g si lo instalaste de forma global. Después comprueba que la carpeta spicyapi ha desaparecido.

  npx skills remove spicyapi

• Si lo instalaste con el instalador del paquete: borra la carpeta spicyapi, desde el Finder o el Explorador de archivos, o desde una terminal:

  # macOS y Linux: usa la carpeta en la que lo instalaste
  rm -rf ~/.agents/skills/spicyapi

  # Windows PowerShell
  Remove-Item -Recurse -Force "$HOME\.agents\skills\spicyapi"

  Revisa la ruta dos veces antes de pulsar Enter: debe terminar en spicyapi.

Después, inicia una sesión nueva para que el asistente deje de usar el Skill.

Solución de problemas

Código fuente

El paquete tiene licencia MIT y se desarrolla en abierto en github.com/spicyapi-ai/spicy-skill. Ahí puedes leer las instrucciones que el Skill instala de verdad, avisar de un comportamiento que no coincida con lo descrito o proponer un cambio.

Siguientes pasos