# vtex-io-masterdata

Walks you through Master Data v2 in VTEX IO apps and pushes back when the data belongs somewhere else.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1200 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-masterdata/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/vtex-io-masterdata

## What it does

The skill fires whenever a VTEX IO app needs its own persistence: reviews, wishlists, form submissions, config records. It does not jump straight to code. First it makes you argue why Master Data is the right store, because Catalog may fit product and SKU data better, OMS already owns orders, and an external database can win on workload shape.

Then the practical side. Entities and JSON Schema through the `masterdata` builder, CRUD via `ctx.clients.masterdata`, search and scroll, triggers on data changes, schema lifecycle. Synchronous Master Data calls on the purchase path — cart, payment, order placement — get their own treatment: without a latency budget and failure analysis, the skill says keep them out. Storefront and partner access goes through a service that handles auth and rate limits, not straight into the store.

Housekeeping is covered too: auditing existing entities, counting documents with `REST-Content-Range` headers, bulk imports as `.jsonl` with checkpoints and backoff on HTTP 429, and the 60-schema ceiling. App logs belong in the logger and caches in VBase, and the skill says so.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills vtex-io-masterdata
```

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-masterdata -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-masterdata/SKILL.md

## When to use it
- decide whether custom data needs a Master Data entity at all
- define JSON Schema without burning through the schema limit
- keep synchronous Master Data calls off the checkout path
- import tens of thousands of documents without hitting 429 and restarting
- sort logs, caches and business data into the right stores

## Example prompts
- Check with vtex-io-masterdata whether reviews belong in Master Data or Catalog
- Define the entity and JSON Schema for a wishlist using the masterdata builder
- Set up scrollDocuments and pagination for an entity with a large document count

## Similar
- [prisma-client-api](https://affpapa.org/en/nevibecode/skills/prisma-client-api.md) — skill · 391400 installs
- [spring-boot-crud-patterns](https://affpapa.org/en/nevibecode/skills/spring-boot-crud-patterns.md) — skill · 3900 installs
- [catalyst-datastore](https://affpapa.org/en/nevibecode/skills/catalyst-datastore.md) — skill · 1000 installs
- [dataverse-python-quickstart](https://affpapa.org/en/nevibecode/skills/dataverse-python-quickstart.md) — skill · 8700 installs
- [cloudbase-document-database-in-wechat-miniprogram](https://affpapa.org/en/nevibecode/skills/cloudbase-document-database-in-wechat-miniprogram.md) — skill · 1500 installs
- [typespec-api-operations](https://affpapa.org/en/nevibecode/skills/typespec-api-operations.md) — skill · 8800 installs

From the same set: [vtex/skills](https://affpapa.org/en/nevibecode/by/vtex/skills.md) — 8 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