Agent Skill

Se você usa um assistente de programação com IA, como Claude Code, Codex ou Cursor, o Skill da SpicyAPI ensina a ele como trabalhar direito com a SpicyAPI. Você instala uma vez. Depois disso, pode dizer "adicione geração de imagens da SpicyAPI ao meu app" e o assistente segue as regras da SpicyAPI em vez de chutar.

Você não precisa ser desenvolvedor para acompanhar esta página. Se você sabe colar um comando num terminal, consegue instalar o Skill.

O que é um Skill

Um Skill é uma pasta de instruções escritas para um assistente de IA, e não para pessoas. Pense nele como o manual de procedimentos que você entregaria a um colega recém-chegado: ele não faz o trabalho sozinho, mas diz a quem faz quais passos seguir, em que ordem e o que nunca fazer.

Assistentes de IA sabem muito sobre programação em geral, mas não têm um conhecimento confiável das regras específicas da SpicyAPI. Deixado para adivinhar, um assistente pode:

• inventar um ID de modelo ou um campo de entrada que não existe;
• colar a sua chave de API direto no seu código;
• enviar a mesma requisição paga duas vezes depois de uma instabilidade de rede, e pagar duas vezes;
• entregar a você um link de resultado que para de funcionar poucos dias depois.

Com o Skill instalado, o assistente lê as regras da SpicyAPI antes de começar. Na prática, funciona assim:

1. A pasta do Skill fica num lugar que o seu assistente verifica quando uma sessão começa.
2. O assistente lê o resumo de um parágrafo do Skill. Quando o seu pedido envolve a SpicyAPI, ele abre as instruções completas. Você não precisa mencionar o Skill pelo nome.
3. Ele segue essas instruções enquanto escreve código ou roda comandos para você.

Três fatos que vale saber desde já:

• É só texto. Arquivos Markdown e YAML: nenhum programa, nenhum script, nada que rode quando você instala. Você pode abrir todos os arquivos num editor de texto; veja O que tem dentro.
• Não contém chave de API e não faz chamadas. Sozinho, ele não tem como acessar a sua conta nem gastar dinheiro.
• É gratuito e de código aberto. Tem licença MIT, é publicado no npm como @spicyapi/skill e é desenvolvido abertamente em github.com/spicyapi-ai/spicy-skill.

Skill, MCP, SDK e CLI

A SpicyAPI tem quatro ferramentas oficiais. Elas resolvem problemas diferentes e foram feitas para ser usadas juntas.

O Skill não substitui nenhuma delas. Ele diz ao assistente como usá-las: as ferramentas MCP quando estão conectadas, a CLI para operações avulsas e o SDK da sua linguagem para o código que vai para dentro da sua aplicação.

• Só o Skill. O assistente escreve código de integração correto para o seu projeto, mas não consegue consultar nada na sua conta nem rodar tarefas para você.
• Só o MCP. O assistente consegue agir na sua conta, mas precisa descobrir sozinho, toda vez, a ordem certa dos passos.
• Os dois. O assistente consegue testar coisas para você e faz isso do jeito documentado. Se você quer que o seu assistente rode tarefas de verdade, instale os dois. Eles não entram em conflito.

No que ele ajuda

A coluna da esquerda é o que você pede. A da direita é o que o Skill faz o assistente cumprir enquanto entrega.

O que ele não faz

• Gastar dinheiro por conta própria. O Skill é texto e não consegue chamar nada. Se o seu assistente também tiver o servidor MCP ou a CLI e uma chave de API, ele pode criar tarefas pagas. O Skill manda o assistente mostrar o preço e obter antes a sua confirmação explícita, a não ser que o seu pedido já tenha autorizado claramente aquela execução paga exata. Com o servidor MCP, toda ação paga ainda para numa confirmação que o assistente não tem como pular.
• Inventar recursos. Ele não escreve chamadas para coisas que a API pública não oferece, como cancelar uma tarefa, apagar o registro de uma tarefa ou reenviar um webhook.
• Mexer nas configurações da sua conta. Cadastro, login, pagamentos, adição de saldo, membros da equipe, pedidos de privacidade e encerramento da conta ficam no console da SpicyAPI. O assistente não tenta automatizá-los.
• Fingir um teste. Se você pedir um teste de verdade, ele faz uma requisição real (e possivelmente paga, depois da sua confirmação) e relata o que realmente aconteceu. Um mock que passou nunca é relatado como "verificado".
• Acrescentar uma configuração de conteúdo. A SpicyAPI não tem parâmetro de modo de conteúdo nem revisão de conteúdo requisição por requisição, e o Skill não inventa nenhum. Quem decide o que é possível é o modelo que você escolher.

Antes de começar

Você precisa de quatro coisas. Só as três primeiras são necessárias para instalar.

1. Um assistente de programação com IA que suporte Agent Skills. Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf e muitos outros suportam. O Skill usa o formato portátil de pasta dos Agent Skills, então funciona com qualquer assistente que leia esse formato. Se não tiver certeza sobre o seu, procure "skills" na documentação dele.

2. Node.js 22 ou mais recente, que fornece o comando npx. Confira com:

   node --version

   O instalador skills hoje pede Node.js 22.20 ou mais recente, e o instalador do próprio pacote precisa da 22.13 ou mais recente. Se o comando não for encontrado ou a versão for menor, instale a versão LTS em nodejs.org e abra um terminal novo.

3. Um terminal. No macOS, o aplicativo Terminal. No Windows, o PowerShell. Rode os comandos a partir da pasta do seu projeto se quiser uma instalação por projeto.

4. Uma chave de API da SpicyAPI, quando você começar a chamar a API. Instalar o Skill não exige chave. Crie uma no console; ela começa com sk-spicy- e aparece uma única vez. Guarde-a numa variável de ambiente chamada SPICY_API_KEY e nunca cole a chave em si numa conversa com o seu assistente. Veja Autenticação.

Instalar

Há duas formas de instalar. As duas colocam os mesmos arquivos no lugar. Use a primeira, a menos que tenha um motivo para não usar.

npx skills add spicyapi-ai/spicy-skill

# Claude Code, só neste projeto
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex, em todos os projetos
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code e Codex, em todos os projetos, sem perguntas
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

Confira se funciona

npx skills list      # Skills instalados no projeto atual
npx skills list -g   # Skills instalados para todos os projetos

Exemplos de pedidos

Cole qualquer um destes no seu assistente e ajuste os detalhes. Mencione a SpicyAPI no pedido, para que o assistente saiba que o Skill se aplica.

Se você já sabe qual modelo quer, copie o ID exato dele na aba API da página do modelo ou no catálogo atual autenticado (GET /api/v1/models) e coloque-o no pedido. Os exemplos trazem MODEL_ID_FROM_CATALOG no lugar desse ID; é um marcador, não um ID real. Se você não tiver um, peça ao assistente que escolha no catálogo atual. Veja Catálogo de modelos e schemas.

Adicionar um endpoint de imagens a um app Next.js

Adicione ao meu app Next.js uma rota de API do lado do servidor que receba um prompt de texto, gere uma imagem com a SpicyAPI usando o modelo MODEL_ID_FROM_CATALOG, espere o resultado e retorne o link da imagem. Leia a chave de API de SPICY_API_KEY.

No que o Skill faz o assistente prestar atenção:

• A chave fica no seu servidor, em SPICY_API_KEY. A sua página web chama a sua rota; ela nunca chama a SpicyAPI com a chave.
• Ele lê os campos de entrada atuais desse modelo no catálogo atual antes de montar a requisição.
• Ele pede antes uma cotação exata e mostra a você o custo estimado e a cobrança máxima. A requisição paga leva essa cotação confirmada.
• Ele cria uma chave de idempotência para a geração e a reaproveita se a requisição estourar o tempo.
• Ele espera com um prazo e depois confere o state da tarefa: uma espera que terminou não é o mesmo que uma geração que deu certo.

Receber resultados com um webhook no Express

Adicione ao meu servidor Express um endpoint de webhook que receba os resultados das tarefas da SpicyAPI, verifique a assinatura usando SPICY_WEBHOOK_SECRET e salve o link do resultado no meu banco de dados.

• Ele verifica a assinatura contra o corpo bruto exato da requisição antes de interpretá-lo como JSON.
• Ele usa o request_id da entrega para ignorar duplicatas, porque o mesmo evento pode chegar mais de uma vez.
• Ele lê o resultado direto de um webhook completo e verificado, sem fazer uma consulta extra.

Copiar os vídeos prontos para o seu próprio armazenamento

Quando uma tarefa de vídeo da SpicyAPI der certo, baixe o vídeo e envie para o meu bucket S3, depois guarde o meu próprio link no lugar do link da SpicyAPI.

• Os links de resultado são temporários e os arquivos gerados ficam guardados por cerca de 14 dias, então ele salva uma cópia durável sob o seu controle.
• Ele não envia a sua chave de API ao baixar de um link de resultado.
• Se um link expirou, ele pede de novo a mesma tarefa à SpicyAPI para receber um link novo. Ele nunca cria uma tarefa nova só para conseguir um link.

Transformar a foto de um usuário em vídeo

Deixe os usuários enviarem uma foto no meu app e transforme essa foto num vídeo curto com a SpicyAPI.

• Ele envia primeiro o arquivo para a SpicyAPI e coloca na requisição o endereço spicy:// retornado, em vez de colar o arquivo como base64.
• Ele respeita os limites de upload: 10 MiB para imagens e 90 MiB para vídeo MP4 ou WebM e áudio MP3 ou WAV.
• Uma foto que já está num link HTTPS público pode ser passada diretamente, sem upload.

Tratar novas tentativas e saldo baixo

Faça a minha integração com a SpicyAPI lidar com falhas: tentar de novo quando a rede estourar o tempo sem pagar duas vezes, mostrar uma mensagem clara quando o saldo da minha conta estiver baixo e diminuir o ritmo quando eu atingir o limite de requisições.

• Depois de um tempo esgotado, ele tenta de novo com a mesma chave de idempotência, então uma nova tentativa não consegue criar uma segunda tarefa paga.
• Ele não repete "saldo insuficiente" (código 40201); o seu usuário vê uma mensagem clara e você adiciona saldo no console.
• Ele espera o tempo que o Retry-After indicar antes de tentar de novo.
• Se a cotação tiver expirado ou o preço tiver mudado (código 40901), ele pede uma cotação nova e pergunta a você de novo, em vez de abrir mão da conferência de preço.
• Ele sabe que repetir uma tarefa que falhou cria uma tarefa nova que pode ser cobrada de novo, então só faz isso quando você quer uma nova tentativa.

Gerar um lote

Gere com a SpicyAPI fotos de produto para os 20 itens de products.csv, no máximo 3 de cada vez, e registre o ID de cada tarefa.

• A SpicyAPI não tem endpoint de lote, então ele roda um número limitado de requisições por vez.
• Cada item recebe a sua própria chave de idempotência e o seu próprio preço.
• Ele registra o ID de cada tarefa assim que ela é aceita.
• Se um item estourar o tempo, ele recupera só esse item e nunca reenvia o lote inteiro.

O que tem dentro

A pasta instalada fica assim:

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

O assistente só abre os dois arquivos de referência quando uma tarefa precisa deles, o que deixa a memória de trabalho dele livre para o seu projeto. Para ler os arquivos antes de instalar, rode npx @spicyapi/skill path: ele mostra a pasta em que o pacote os guarda.

O Skill orienta o assistente a configurar o seu código e as suas ferramentas com estas variáveis de ambiente. O Skill em si não lê nenhuma delas.

Atualizar e remover

Atualizar

O Skill muda quando o fluxo de trabalho recomendado pela SpicyAPI muda, e as cópias instaladas não se atualizam sozinhas. A pasta instalada não traz número de versão, então reinstalar é o jeito mais simples de ter certeza de que você está com a versão atual.

• Instalado com npx skills add: rode o mesmo comando de novo, com o mesmo escopo e os mesmos assistentes. Ele substitui os arquivos instalados pelo que o repositório tem naquele momento, então uma atualização chega assim que é publicada — não há o que esperar.

• Instalado com o instalador do pacote: rode-o de novo com --force e o mesmo --target. Acrescentar @latest faz o npx buscar o pacote mais novo em vez de reaproveitar um que está em cache:

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

Remover

Remover o Skill não afeta a sua conta na SpicyAPI, as suas chaves de API nem nenhum código que o assistente já escreveu.

• Instalado com npx skills add: rode isto na mesma pasta de projeto, acrescentando -g se a instalação foi global. Depois confira se a pasta spicyapi sumiu.

  npx skills remove spicyapi

• Instalado com o instalador do pacote: apague a pasta spicyapi. Pelo Finder, pelo Explorador de Arquivos ou por um terminal:

  # macOS e Linux: use a pasta em que você instalou
  rm -rf ~/.agents/skills/spicyapi

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

  Confira o caminho duas vezes antes de apertar Enter: ele precisa terminar em spicyapi.

Depois, abra uma sessão nova para que o assistente pare de usar o Skill.

Solução de problemas

Código-fonte

O pacote tem licença MIT e é desenvolvido abertamente em github.com/spicyapi-ai/spicy-skill. É lá que você lê as instruções que o Skill realmente instala, relata um comportamento diferente do descrito aqui ou propõe uma mudança.

Próximos passos