vtex-io-service-apps — скилл для Claude Code: суть и установка
Помогает проектировать бэкенд-сервисы в VTEX IO на Node.js. Задаёт правила для роутов в service.json, middleware и типизированных клиентов @vtex/api.
npx skills add vtex/skills --skill vtex-io-service-apps -a claude-codeЧто делает vtex-io-service-apps
Скилл настраивает точку входа сервиса в node/index.ts на основе класса Service. Он помогает связать маршруты из service.json, события и резолверы GraphQL с контекстом запроса ctx.
Сетевые запросы делятся по классам. Для внутренних шлюзов VTEX используется JanusClient, а для сторонних сервисов подходит ExternalClient. Для работы с базой документов берут MasterDataClient. Новые адаптеры регистрируют в классе IOClients, где они создаются только при первом обращении через метод getOrSet.
Прямые вызовы fetch или axios заблокирует файрвол платформы. Поэтому весь сетевой обмен должен идти через обёртки @vtex/api. Создавать экземпляры классов через оператор new тоже запрещено: обработчики обязаны получать их из ctx.clients, иначе сервис останется без токенов авторизации и метрик.
Какие задачи решает
- Связать маршруты из
service.jsonс цепочками middleware в Node.js - Настроить интеграцию со сторонним API через
ExternalClient - Зарегистрировать клиент в
IOClientsс ленивой инициализацией - Заменить прямые вызовы
fetchилиaxiosна клиенты@vtex/api
Примеры запросов агенту
- Напиши middleware для маршрута в
service.json, который читает профиль клиента черезctx.clients - Создай класс клиента для внешнего REST API на базе
ExternalClientс передачей ключа в заголовке - Настрой точку входа
node/index.tsс классомServiceи типизированным состояниемctx.state
Как установить vtex-io-service-apps
1Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -a claude-code2Вручную: положить файлы
~/.claude/skills/vtex-io-service-apps/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/vtex-io-service-apps/
1Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -a codex2Вручную: положить файлы
.agents/skills/vtex-io-service-apps/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -a cursor2Вручную: положить файлы
.cursor/skills/vtex-io-service-apps/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install vtex/skills vtex-io-service-apps2Вручную: положить файлы
.github/skills/vtex-io-service-apps/SKILL.md1Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -a gemini-cli2Командой платформы
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-service-appsВручную: положить файлы
.devin/skills/vtex-io-service-apps/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о vtex-io-service-apps
Как установить vtex-io-service-apps в Claude Code?
Выполните команду npx skills add vtex/skills --skill vtex-io-service-apps -a claude-code. Файл запишется по пути ~/.claude/skills/vtex-io-service-apps/SKILL.md.
Для чего нужен скилл vtex-io-service-apps?
Он обучает ассистента правилам архитектуры бэкенда VTEX IO в каталоге node/. Скилл следит за корректным использованием Service, структуры IOClients и встроенного кеширования.
Почему нельзя использовать axios или fetch в коде сервиса?
Исходящий трафик рантайма VTEX IO фильтруется файрволом, пропускающим только запросы через @vtex/api. Обычные библиотеки лишены автоматической подстановки токенов авторизации и метрик платформы.
