Agent Skill

Если вы пользуетесь ИИ-ассистентом для программирования, например Claude Code, Codex или Cursor, Skill SpicyAPI научит его правильно работать со SpicyAPI. Устанавливается он один раз. После этого можно сказать «добавь в моё приложение генерацию изображений через SpicyAPI», и ассистент будет следовать правилам SpicyAPI, а не действовать наугад.

Чтобы пройти по этой странице, не нужно быть разработчиком. Если вы умеете вставить команду в терминал, вы сможете установить Skill.

Что такое Skill

Skill — это папка с инструкциями, написанными не для людей, а для ИИ-ассистента. Представьте регламент, который вручают новому коллеге: сам он работу не делает, но подсказывает тому, кто её делает, какие шаги выполнять, в каком порядке и чего не делать никогда.

ИИ-ассистенты много знают о программировании в целом, но надёжных знаний о конкретных правилах SpicyAPI у них нет. Действуя наугад, ассистент может:

• придумать ID модели или поле входных данных, которых не существует;
• вставить ваш API-ключ прямо в код;
• после сбоя сети отправить один и тот же платный запрос дважды и дважды за него заплатить;
• выдать вам ссылку на результат, которая через несколько дней перестанет работать.

С установленным Skill ассистент читает правила SpicyAPI до того, как возьмётся за работу. На практике это выглядит так:

1. Папка Skill лежит там, куда ваш ассистент заглядывает при запуске сеанса.
2. Ассистент читает краткое описание Skill в один абзац. Когда ваш запрос касается SpicyAPI, он открывает полные инструкции. Называть Skill по имени не нужно.
3. Пока ассистент пишет для вас код или выполняет команды, он следует этим инструкциям.

Три факта, которые стоит знать заранее:

• Это только текст. Файлы Markdown и YAML: никаких программ, никаких скриптов, ничего, что запускается при установке. Любой файл можно открыть в текстовом редакторе; см. Что внутри.
• В нём нет API-ключа, и сам он ничего не вызывает. Сам по себе он не может ни добраться до вашего аккаунта, ни потратить деньги.
• Он бесплатный и с открытым исходным кодом. Распространяется по лицензии MIT, опубликован в npm как @spicyapi/skill и разрабатывается открыто по адресу github.com/spicyapi-ai/spicy-skill.

Skill, MCP, SDK и CLI

У SpicyAPI четыре официальных инструмента. Они решают разные задачи и задуманы так, чтобы работать вместе.

Skill не заменяет ни один из них. Он объясняет ассистенту, как ими пользоваться: инструментами MCP, когда они подключены; CLI для разовых операций; SDK для вашего языка — для кода, который войдёт в ваше приложение.

• Только Skill. Ассистент пишет для вашего проекта правильный код интеграции, но не может ничего посмотреть в вашем аккаунте или запустить задачи за вас.
• Только MCP. Ассистент может действовать в вашем аккаунте, но каждый раз вынужден сам выяснять правильный порядок шагов.
• И то и другое. Ассистент может пробовать за вас и делает это так, как описано в документации. Если хотите, чтобы ассистент запускал настоящие задачи, установите оба инструмента. Они не конфликтуют.

С чем он помогает

В левом столбце то, о чём вы просите. В правом то, что Skill заставляет ассистента делать, пока он выполняет просьбу.

Чего он делать не будет

• Тратить деньги по своей инициативе. Skill — это текст, и вызвать он ничего не может. Если у вашего ассистента вдобавок есть MCP-сервер или CLI и API-ключ, он может создавать платные задачи. Skill велит ему сначала показать вам цену и получить ваше явное подтверждение, если только ваш запрос уже однозначно не разрешил именно этот платный запуск. С MCP-сервером каждое платное действие дополнительно останавливается на подтверждении, которое ассистент пропустить не может.
• Выдумывать возможности. Он не станет писать вызовы того, чего публичный API не предлагает: отмены задачи, удаления записи о задаче или повторной отправки вебхука.
• Трогать настройки аккаунта. Регистрация, вход, платежи, пополнения, участники команды, запросы о персональных данных и закрытие аккаунта остаются в консоли SpicyAPI. Ассистент не будет пытаться их автоматизировать.
• Подделывать тесты. Если вы просите настоящий тест, он делает настоящий запрос (возможно, платный, и только после вашего подтверждения) и сообщает, что произошло на самом деле. Пройденная проверка на заглушках (моках) никогда не выдаётся за «проверено».
• Добавлять настройку контента. В SpicyAPI нет флага режима контента и нет проверки содержимого каждого запроса, и Skill ничего подобного не выдумывает. Что можно делать, определяет выбранная вами модель.

Перед началом

Вам понадобятся четыре вещи. Для установки достаточно первых трёх.

1. ИИ-ассистент для программирования, который поддерживает Agent Skills. Их поддерживают Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf и многие другие. Skill использует переносимый формат папок Agent Skills, поэтому работает с любым ассистентом, который читает этот формат. Если не уверены насчёт своего, поищите в его документации слово «skills».

2. Node.js 22 или новее: он даёт команду npx. Проверьте так:

   node --version

   Установщику skills сейчас нужен Node.js 22.20 или новее, а собственному установщику пакета нужна версия 22.13 или новее. Если команда не найдена или версия ниже, установите LTS-версию с nodejs.org и откройте новый терминал.

3. Терминал. На macOS это приложение «Терминал», на Windows — PowerShell. Если нужна установка только для одного проекта, запускайте команды из папки этого проекта.

4. API-ключ SpicyAPI, когда начнёте вызывать API. Для установки Skill он не нужен. Создайте ключ в консоли; он начинается с sk-spicy- и показывается только один раз. Храните его в переменной окружения SPICY_API_KEY и никогда не вставляйте сам ключ в чат с ассистентом. См. Аутентификация.

Установка

Установить Skill можно двумя способами. Оба раскладывают одни и те же файлы. Выбирайте первый, если нет причин поступить иначе.

npx skills add spicyapi-ai/spicy-skill

# Claude Code, только этот проект
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex, все проекты
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code и Codex, все проекты, без вопросов
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

Проверьте, что всё работает

npx skills list      # Skills, установленные в текущем проекте
npx skills list -g   # Skills, установленные для всех проектов

Примеры запросов

Вставьте любой из этих запросов в ассистента и поправьте детали. Упоминайте в запросе SpicyAPI, чтобы ассистент понял, что здесь применим Skill.

Если вы уже знаете, какая модель вам нужна, скопируйте её точный ID со вкладки API на странице модели или из аутентифицированного актуального каталога (live catalog, GET /api/v1/models) и вставьте его в запрос. В примерах на месте этого ID написано MODEL_ID_FROM_CATALOG: это заполнитель, а не настоящий ID. Если ID у вас нет, попросите ассистента выбрать модель из актуального каталога. См. Модели и эндпоинты.

Эндпоинт для изображений в приложении на Next.js

Добавь в моё приложение на Next.js серверный API-маршрут, который принимает текстовый промпт, генерирует изображение через SpicyAPI моделью MODEL_ID_FROM_CATALOG, дожидается результата и возвращает ссылку на изображение. API-ключ читай из SPICY_API_KEY.

За чем Skill велит ассистенту следить:

• Ключ остаётся на вашем сервере в SPICY_API_KEY. Ваша веб-страница обращается к вашему маршруту и никогда не вызывает SpicyAPI с ключом сама.
• Прежде чем составлять запрос, ассистент читает из актуального каталога текущие поля входных данных этой модели.
• Сначала он получает точный расчёт стоимости и показывает вам ориентировочную стоимость и максимальную сумму списания. Платный запрос отправляется вместе с этим подтверждённым расчётом.
• Он создаёт один ключ идемпотентности на генерацию и отправляет его повторно, если время ожидания запроса истекло.
• Он ждёт с крайним сроком, а затем проверяет state задачи: закончившееся ожидание ещё не означает успешную генерацию.

Приём результатов через вебхук в Express

Добавь в мой сервер на Express эндпоинт вебхука, который принимает результаты задач SpicyAPI, проверяет подпись с помощью SPICY_WEBHOOK_SECRET и сохраняет ссылку на результат в мою базу данных.

• Ассистент проверяет подпись по точному исходному телу запроса до того, как разбирать его как JSON.
• Он использует request_id доставки, чтобы отбрасывать дубликаты: одно и то же событие может прийти больше одного раза.
• Результат он берёт прямо из полного проверенного вебхука, не делая лишнего запроса.

Копирование готовых видео в собственное хранилище

Когда видеозадача SpicyAPI завершается успешно, скачай видео, загрузи его в мой бакет S3 и сохраняй мою собственную ссылку вместо ссылки SpicyAPI.

• Ссылки на результаты временные, а сгенерированные файлы хранятся около 14 дней, поэтому ассистент сохраняет долговечную копию под вашим контролем.
• При скачивании по ссылке на результат он не отправляет ваш API-ключ.
• Если срок действия ссылки истёк, он снова запрашивает у SpicyAPI ту же задачу, чтобы получить свежую ссылку. Новую задачу только ради ссылки он никогда не создаёт.

Видео из фотографии пользователя

Дай пользователям загружать фото в моём приложении и превращать его в короткое видео через SpicyAPI.

• Ассистент сначала загружает файл в SpicyAPI и подставляет в запрос полученный адрес spicy://, а не вставляет файл в виде base64.
• Он соблюдает ограничения на загрузку: 10 MiB для изображений, 90 MiB для видео MP4 или WebM и аудио MP3 или WAV.
• Фото, которое уже доступно по публичной ссылке HTTPS, можно передать напрямую, без загрузки.

Повторы и нехватка баланса

Сделай так, чтобы моя интеграция со SpicyAPI справлялась со сбоями: повторяла запросы после сетевых тайм-аутов, не платя дважды, показывала понятное сообщение, когда на балансе аккаунта не хватает денег, и сбавляла темп, когда я упираюсь в лимит запросов.

• После тайм-аута ассистент повторяет запрос с тем же ключом идемпотентности, чтобы повтор не создал вторую платную задачу.
• Ошибку «недостаточно средств» (код 40201) он не повторяет: ваш пользователь видит понятное сообщение, а вы пополняете баланс в консоли.
• Перед новой попыткой он ждёт столько, сколько указано в Retry-After.
• Если срок действия расчёта истёк или цена изменилась (код 40901), он получает новый расчёт стоимости и снова спрашивает вас, а не отказывается от проверки цены.
• Он знает, что повтор завершившейся ошибкой задачи создаёт новую задачу, за которую могут снова списать деньги, поэтому делает это, только когда вам нужна новая попытка.

Пакетная генерация

Сгенерируй через SpicyAPI фотографии товаров для 20 позиций из products.csv, не больше 3 одновременно, и запиши в лог ID каждой задачи.

• В SpicyAPI нет пакетного эндпоинта, поэтому ассистент одновременно запускает только ограниченное число запросов.
• У каждого элемента свой ключ идемпотентности и своя цена.
• ID каждой задачи он записывает сразу, как только задача принята.
• Если время ожидания истекло для одного элемента, он восстанавливает только этот элемент и никогда не отправляет заново всю пачку.

Что внутри

Установленная папка выглядит так:

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

Два справочных файла ассистент открывает, только когда они нужны для задачи: так в его рабочей памяти остаётся место для вашего проекта. Чтобы прочитать файлы до установки, выполните npx @spicyapi/skill path: команда выведет папку, где пакет их хранит.

Skill велит ассистенту настраивать ваш код и инструменты через эти переменные окружения. Сам Skill ни одну из них не читает.

Обновление и удаление

Обновление

Skill меняется, когда меняется рекомендуемый порядок работы со SpicyAPI, а установленные копии сами не обновляются. В установленной папке нет номера версии, поэтому переустановка — самый простой способ убедиться, что у вас актуальная версия.

• Если устанавливали через npx skills add: выполните ту же команду ещё раз, с той же областью действия и теми же ассистентами. Она заменит установленные файлы текущим содержимым репозитория, поэтому обновление доступно сразу после публикации — ждать ничего не нужно.

• Если устанавливали установщиком пакета: запустите его снова с --force и тем же --target. Если добавить @latest, npx скачает самый новый пакет, а не возьмёт закэшированный:

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

Удаление

Удаление Skill не затрагивает ваш аккаунт SpicyAPI, ваши API-ключи и код, который ассистент уже написал.

• Если устанавливали через npx skills add: выполните эту команду из той же папки проекта, а если установка была глобальной, добавьте -g. Затем убедитесь, что папки spicyapi больше нет.

  npx skills remove spicyapi

• Если устанавливали установщиком пакета: удалите папку spicyapi в Finder или Проводнике либо из терминала:

  # macOS и Linux: укажите папку, в которую устанавливали
  rm -rf ~/.agents/skills/spicyapi

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

  Прежде чем нажать Enter, дважды проверьте путь: он должен заканчиваться на spicyapi.

После этого начните новый сеанс, чтобы ассистент перестал пользоваться Skill.

Устранение неполадок

Исходный код

Пакет распространяется под лицензией MIT и разрабатывается открыто по адресу github.com/spicyapi-ai/spicy-skill. Там же можно прочитать инструкции, которые Skill на самом деле устанавливает, сообщить о поведении, которое расходится с описанным, или предложить изменение.

Что дальше