vtex-io-app-settings — скилл для Claude Code, установка
Скилл помогает описать настройки VTEX IO приложения через settingsSchema и безопасно читать их в коде. Пригодится, когда мерчант должен менять поведение приложения сам.
npx skills add vtex/skills --skill vtex-io-app-settings -a claude-codeЧто делает vtex-io-app-settings
Скилл подсказывает агенту, куда класть конфигурацию VTEX IO приложения. Значения, общие для приложения или аккаунта, идут в settingsSchema и правятся в VTEX Admin. Всё, что меняется от страницы или блока, относится к store/contentSchemas.json. Схема должна быть настоящей: со properties, required, default, enum и format, а не голым type: object.
На бэкенде настройки читаются через ctx.clients.apps.getAppSettings с идентификатором самого приложения, а нормализацию и значения по умолчанию лучше держать в одном хелпере. Секреты вроде API-ключей остаются на сервере, в ответы и логи не попадают. Подсказка format: password помогает некоторым потребителям маскировать поле, но защитой её скилл не считает. Фронтенд видит только поля с access: public через publicSettingsForApp.
Если чтение собственных настроек даёт 403, добавлять read-workspace-apps в манифест неверно. Для конфигурации, общей для нескольких приложений, скилл предлагает отдельное приложение на builder configuration. Про service.json, сущности Master Data и авторизацию маршрутов он не говорит.
Какие задачи решает
- описать схему настроек с
required,defaultиenum - спрятать API-ключ внешнего сервиса от фронтенда
- решить, что идёт в
settingsSchema, а что вcontentSchemas.json - открыть фронтенду безопасные поля через
publicSettingsForApp - собрать чтение настроек в один хелпер с запасными значениями
Примеры запросов агенту
- Опиши
settingsSchemaдля моего VTEX IO приложения: переключатель модерации, режим sandbox/production и API-ключ - Проверь, не отдаёт ли какой-нибудь маршрут настройки приложения вместе с ключом
- Это значение лучше положить в
settingsSchemaили вcontentSchemas.json?
Как установить vtex-io-app-settings
1Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a claude-code2Вручную: положить файлы
~/.claude/skills/vtex-io-app-settings/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/vtex-io-app-settings/
1Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a codex2Вручную: положить файлы
.agents/skills/vtex-io-app-settings/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a cursor2Вручную: положить файлы
.cursor/skills/vtex-io-app-settings/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install vtex/skills vtex-io-app-settings2Вручную: положить файлы
.github/skills/vtex-io-app-settings/SKILL.md1Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a gemini-cli2Командой платформы
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-app-settingsВручную: положить файлы
.devin/skills/vtex-io-app-settings/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о vtex-io-app-settings
Как установить vtex-io-app-settings в Claude Code?
Выполните npx skills add vtex/skills --skill vtex-io-app-settings -a claude-code. Файл скилла появится в ~/.claude/skills/vtex-io-app-settings/SKILL.md.
Что делает vtex-io-app-settings?
Помогает агенту проектировать settingsSchema, читать настройки через getAppSettings и не отдавать секреты наружу. Ещё разбирает, что должно быть настройкой приложения, а что нет.
Чем settingsSchema отличается от contentSchemas.json?
settingsSchema описывает настройки всего приложения в Admin, а store/contentSchemas.json задаёт конфигурацию блоков Store Framework, которая зависит от страницы или экземпляра блока.
