# vtex-io-service-configuration-apps

Guides the agent through building VTEX IO configuration apps using the configuration builder. Helps inject decoupled workspace settings into service runtimes.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1100 installs · ★ 46
- Author: vtex
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/vtex/skills/tree/HEAD/skills/vtex-io-service-configuration-apps/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/vtex-io-service-configuration-apps

## What it does

This skill defines architectural patterns for externalizing VTEX IO service settings into separate configuration apps. Instead of bundling values into local settings, the service app specifies the data contract in `configuration/schema.json`. The configuration app then supplies concrete definitions through the `configuration` builder.

Separation of concerns is mandatory here. Configuration apps must not declare `node` or `graphql` builders. To consume settings, service routes or events in `node/service.json` need `settingsType: "workspace"`, or the `@settings` directive in GraphQL. The handler then retrieves payload data straight from `ctx.vtex.settings`.

Making ad hoc HTTP requests to fetch these values defeats the architecture. If a service encounters workspace permission issues while resolving settings, inspect whether the `read-workspace-apps` policy is missing. Extra properties should be blocked in schema contracts with `additionalProperties: false`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-service-configuration-apps -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/vtex-io-service-configuration-apps/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/vtex-io-service-configuration-apps/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-service-configuration-apps -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/vtex-io-service-configuration-apps/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-service-configuration-apps -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/vtex-io-service-configuration-apps/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills vtex-io-service-configuration-apps
```

2. **Manually: put the files in place**
- File: `.github/skills/vtex-io-service-configuration-apps/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-service-configuration-apps -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-service-configuration-apps
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/vtex-io-service-configuration-apps/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-service-configuration-apps -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vtex/skills/tree/HEAD/skills/vtex-io-service-configuration-apps/SKILL.md

## When to use it
- decouple configuration lifecycles from backend service deployments
- register service entrypoints with settingsType: workspace or @settings
- declare strict JSON Schema contracts in configuration/schema.json
- extract injected settings from ctx.vtex.settings without extra HTTP calls

## Example prompts
- Structure a dedicated configuration app for our shipping-service using the configuration builder.
- Update node/service.json to expose routes for workspace settings injection.
- Create a closed configuration/schema.json schema to validate injected payment configuration.

## Similar
- [mcp-builder](https://affpapa.org/en/nevibecode/skills/mcp-builder.md) — skill · 130949 installs
- [claude-api](https://affpapa.org/en/nevibecode/skills/claude-api.md) — skill · 74198 installs
- [lark-im](https://affpapa.org/en/nevibecode/skills/lark-im.md) — skill · 472900 installs
- [lark-event](https://affpapa.org/en/nevibecode/skills/lark-event.md) — skill · 466800 installs
- [caveman-discover](https://affpapa.org/en/nevibecode/skills/caveman-discover.md) — skill · 104400 installs
- [migration](https://affpapa.org/en/nevibecode/skills/migration.md) — skill · 103900 installs

From the same set: [vtex/skills](https://affpapa.org/en/nevibecode/by/vtex/skills.md) — 38 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md