vtex-io-app-settings — Claude Code skill, how to install
Helps an agent define settingsSchema for a VTEX IO app and read the values safely in code. Useful when merchants should change app behavior themselves.
npx skills add vtex/skills --skill vtex-io-app-settings -a claude-codeWhat vtex-io-app-settings does
This skill tells the agent where configuration for a VTEX IO app should live. Values shared across the app or account go into settingsSchema and get edited in VTEX Admin. Anything that differs per page or block belongs in store/contentSchemas.json. The schema itself should be real JSON Schema with properties, required, default, enum and format, not a bare type: object.
On the backend, settings are fetched with ctx.clients.apps.getAppSettings and the app's own ID, and normalization plus defaults sit in one helper. API keys and other secrets stay server-side, out of responses and logs. A format: password hint lets some consumers mask a field, but the skill treats it as a bonus, not protection. Frontend code sees only fields marked access: public, through publicSettingsForApp.
If reading the app's own settings returns a 403, adding read-workspace-apps to the manifest is the wrong fix. For configuration shared between several apps, the skill points to a separate app on the configuration builder. It stays away from service.json, Master Data entity design and route auth.
What it helps with
- write a settings schema with
required,defaultandenum - keep an external service API key away from frontend code
- decide between
settingsSchemaandcontentSchemas.json - expose harmless fields to the storefront via
publicSettingsForApp - centralize settings reads in one helper with fallback values
Example prompts for the agent
- Write a
settingsSchemafor my VTEX IO app with a moderation toggle, a sandbox/production mode and an API key - Check whether any route returns the raw app settings, key included
- Should this value go in
settingsSchemaorcontentSchemas.json?
How to install vtex-io-app-settings
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a claude-code2Manually: put the files in place
~/.claude/skills/vtex-io-app-settings/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vtex-io-app-settings/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a codex2Manually: put the files in place
.agents/skills/vtex-io-app-settings/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a cursor2Manually: put the files in place
.cursor/skills/vtex-io-app-settings/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills vtex-io-app-settings2Manually: put the files in place
.github/skills/vtex-io-app-settings/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-app-settingsManually: put the files in place
.devin/skills/vtex-io-app-settings/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-app-settings -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about vtex-io-app-settings
How do I install vtex-io-app-settings in Claude Code?
Run npx skills add vtex/skills --skill vtex-io-app-settings -a claude-code. The skill file ends up at ~/.claude/skills/vtex-io-app-settings/SKILL.md.
What does vtex-io-app-settings do?
It guides the agent through designing settingsSchema, reading settings with getAppSettings and keeping secrets off the frontend. It also helps judge what belongs in app settings at all.
How is settingsSchema different from contentSchemas.json?
settingsSchema covers app-wide options edited in Admin. store/contentSchemas.json configures Store Framework blocks, so it fits values that change per page or block instance.
