Agent Skill

If you use an AI coding assistant such as Claude Code, Codex or Cursor, the SpicyAPI Skill teaches it how to work with SpicyAPI properly. You install it once. After that you can say "add SpicyAPI image generation to my app" and the assistant follows SpicyAPI's rules instead of guessing.

You don't need to be a developer to follow this page. If you can paste a command into a terminal, you can install the Skill.

What a Skill is

A Skill is a folder of instructions written for an AI assistant rather than for people. Think of it as the operations manual you would hand a new colleague: it doesn't do the work itself, but it tells whoever does the work which steps to take, in what order, and what never to do.

AI assistants know a lot about programming in general, but they have no reliable knowledge of SpicyAPI's specific rules. Left to guess, an assistant may:

• make up a model ID or input field that doesn't exist;
• paste your API key straight into your code;
• send the same paid request twice after a network hiccup, and pay twice;
• hand you a result link that stops working a few days later.

With the Skill installed, the assistant reads SpicyAPI's rules before it starts. This is how it works in practice:

1. The Skill's folder sits in a place your assistant checks when a session starts.
2. The assistant reads the Skill's one-paragraph summary. When your request involves SpicyAPI, it opens the full instructions. You don't have to mention the Skill by name.
3. It follows those instructions while it writes code or runs commands for you.

Three facts worth knowing up front:

• It is only text. Markdown and YAML files: no programs, no scripts, nothing that runs when you install it. You can open every file in a text editor; see What's inside.
• It contains no API key and makes no calls. On its own it cannot reach your account or spend money.
• It is free and open source. MIT-licensed, published on npm as @spicyapi/skill and developed in the open at github.com/spicyapi-ai/spicy-skill.

Skill, MCP, SDK and CLI

SpicyAPI has four official tools. They solve different problems and are designed to be used together.

The Skill doesn't replace any of them. It tells the assistant how to use them: the MCP tools when they are connected, the CLI for one-off operations, and the SDK for your language for code that goes into your application.

• Skill only. The assistant writes correct integration code for your project, but it can't look anything up in your account or run tasks for you.
• MCP only. The assistant can act on your account, but it has to work out the right order of steps by itself every time.
• Both. The assistant can try things for you and does them the documented way. If you want your assistant to run real tasks, install both. They don't conflict.

What it helps with

The left column is what you ask for. The right column is what the Skill makes the assistant do while delivering it.

What it will not do

• Spend money on its own. The Skill is text and can't call anything. If your assistant also has the MCP server or the CLI and an API key, it can create paid tasks. The Skill tells it to show you the price and get your explicit confirmation first, unless your request already clearly authorized that exact paid run. With the MCP server, every paid action additionally stops for a confirmation the assistant cannot skip.
• Invent features. It won't write calls for things the public API doesn't offer, such as cancelling a task, deleting a task record or re-sending a webhook.
• Touch your account settings. Sign-up, login, payments, top-ups, team members, privacy requests and account closure stay in the SpicyAPI console. The assistant won't try to automate them.
• Fake a test. If you ask for a real test, it makes a real (and possibly paid, after your confirmation) request and reports what actually happened. A passing mock is never reported as "verified".
• Add a content setting. SpicyAPI has no content-mode flag and no per-request content review, and the Skill doesn't invent one. The model you choose decides what it can do.

Before you start

You need four things. Only the first three are needed to install.

1. An AI coding assistant that supports Agent Skills. Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf and many others do. The Skill uses the portable Agent Skills folder format, so it works with any assistant that reads that format. If you're unsure about yours, search its documentation for "skills".

2. Node.js 22 or later, which provides the npx command. Check with:

   node --version

   The skills installer currently asks for Node.js 22.20 or later, and the package's own installer needs 22.13 or later. If the command isn't found or the version is lower, install the LTS release from nodejs.org and open a new terminal.

3. A terminal. On macOS, the Terminal app. On Windows, PowerShell. Run the commands from your project folder if you want a per-project install.

4. A SpicyAPI API key, once you start calling the API. Installing the Skill doesn't need one. Create a key in the console; it starts with sk-spicy- and is shown only once. Store it in an environment variable named SPICY_API_KEY and never paste the key itself into a chat with your assistant. See Authentication.

Install

There are two ways to install. Both put the same files in place. Use the first one unless you have a reason not to.

npx skills add spicyapi-ai/spicy-skill

# Claude Code, this project only
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex, every project
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code and Codex, every project, no questions
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

Check that it works

npx skills list      # Skills installed in the current project
npx skills list -g   # Skills installed for every project

Example requests

Paste any of these into your assistant and adjust the details. Mention SpicyAPI in the request so the assistant knows the Skill applies.

If you already know which model you want, copy its exact ID from the model page's API tab or the authenticated live catalog and put it in the request. The examples write MODEL_ID_FROM_CATALOG where that ID goes; it is a placeholder, not a real ID. If you don't have one, ask the assistant to choose from the live catalog. See Model catalog.

Add an image endpoint to a Next.js app

Add a server-side API route to my Next.js app that takes a text prompt, generates an image with SpicyAPI using the model MODEL_ID_FROM_CATALOG, waits for the result and returns the image link. Read the API key from SPICY_API_KEY.

What the Skill has the assistant watch for:

• The key stays on your server in SPICY_API_KEY. Your web page calls your route; it never calls SpicyAPI with the key.
• It reads that model's current input fields from the live catalog before building the request.
• It gets an exact quote first and shows you the estimated cost and maximum charge. The paid request carries that confirmed quote.
• It creates one idempotency key for the generation and reuses it if the request times out.
• It waits with a deadline and then checks the task's state: a wait that ended is not the same as a generation that succeeded.

Receive results with a webhook in Express

Add a webhook endpoint to my Express server that receives SpicyAPI task results, verifies the signature using SPICY_WEBHOOK_SECRET, and saves the result link to my database.

• It verifies the signature against the exact raw request body before parsing it as JSON.
• It uses the delivery's request_id to ignore duplicates, because the same event can arrive more than once.
• It reads the result straight from a complete, verified webhook without making an extra lookup.

Copy finished videos into your own storage

When a SpicyAPI video task succeeds, download the video and upload it to my S3 bucket, then store my own link instead of the SpicyAPI one.

• Result links are temporary and generated files are kept for about 14 days, so it saves a durable copy you control.
• It doesn't send your API key when downloading from a result link.
• If a link has expired, it asks SpicyAPI for the same task again to get a fresh link. It never creates a new task just to get a link.

Turn a user's photo into a video

Let users upload a photo in my app and turn it into a short video with SpicyAPI.

• It uploads the file to SpicyAPI first and puts the returned spicy:// address in the request, instead of pasting the file in as base64.
• It respects the upload limits: 10 MiB for images, 90 MiB for MP4 or WebM video and MP3 or WAV audio.
• A photo that is already at a public HTTPS link can be passed directly, without uploading.

Handle retries and a low balance

Make my SpicyAPI integration handle failures: retry network timeouts without paying twice, show a clear message when my account balance is too low, and back off when I'm rate limited.

• After a timeout it retries with the same idempotency key, so a retry can't create a second paid task.
• It doesn't retry "insufficient balance" (code 40201); your user sees a clear message and you top up in the console.
• It waits for as long as Retry-After says before trying again.
• If the quote has expired or the price has changed (code 40901), it gets a fresh quote and asks you again, rather than dropping the price check.
• It knows that retrying a failed task creates a new task that may be charged again, so it only does that when you want a new attempt.

Generate a batch

Generate product photos with SpicyAPI for the 20 items in products.csv, at most 3 at a time, and log each task ID.

• SpicyAPI has no batch endpoint, so it runs a limited number of requests at a time.
• Each item gets its own idempotency key and its own price.
• It records each task ID as soon as the task is accepted.
• If one item times out, it recovers only that item and never resubmits the whole batch.

What's inside

The installed folder looks like this:

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

The assistant only opens the two reference files when a task needs them, which keeps its working memory free for your project. To read the files before installing, run npx @spicyapi/skill path: it prints the folder where the package keeps them.

The Skill tells the assistant to configure your code and tools with these environment variables. The Skill itself reads none of them.

Updating and removing

Update

The Skill changes when SpicyAPI's recommended workflow changes, and installed copies don't update themselves. The installed folder carries no version number, so reinstalling is the simplest way to be sure you're current.

• Installed with npx skills add: run the same command again, with the same scope and assistants. It replaces the installed files with whatever the repository holds at that moment, so an update reaches you as soon as it lands — there is nothing to wait for.

• Installed with the package installer: run it again with --force and the same --target. Adding @latest makes npx fetch the newest package instead of reusing a cached one:

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

Remove

Removing the Skill doesn't affect your SpicyAPI account, your API keys or any code the assistant already wrote.

• Installed with npx skills add: run this from the same project folder, adding -g if you installed globally. Then check that the spicyapi folder is gone.

  npx skills remove spicyapi

• Installed with the package installer: delete the spicyapi folder. In Finder or File Explorer, or from a terminal:

  # macOS and Linux: use the folder you installed into
  rm -rf ~/.agents/skills/spicyapi

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

  Check the path twice before pressing Enter: it must end in spicyapi.

Start a new session afterwards so the assistant stops using the Skill.

Troubleshooting

Source

The package is MIT-licensed and developed in the open at github.com/spicyapi-ai/spicy-skill. That is where to read the exact instructions the Skill installs, report behaviour that differs from what is described here, or propose a change.

Next steps