# vtex-io-service-paths-and-cdn

Picks the right path prefix in service.json and matches Cache-Control to the data, so edge caching does not serve one shopper's payload to another.

- 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-paths-and-cdn/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/vtex-io-service-paths-and-cdn

## What it does

The skill walks through three prefix options for VTEX IO routes: public, `/_v/segment/` and `/_v/private/`. The choice decides which cookies reach your service and whether VTEX caches the response at the edge. Public paths give no guarantee of request cookies, segment paths receive `vtex_segment` and cache per segment, private paths add `vtex_session` and skip edge caching entirely.

Inside are decision rules, a list of common failure modes and a review checklist. Classify the response first — anonymous, segment-scoped or authenticated — then assign the path and headers. A route returning order history, addresses or tokens on a public path with a long `max-age` leaks data between shoppers. One trap worth knowing: the path prefix and the `"public": true` field in `service.json` control different things, and they get mixed up often.

Field-level GraphQL caching lives in `vtex-io-graphql-api`; LRU, VBase and stale-while-revalidate belong to `vtex-io-application-performance`. This one stays on routes and response headers.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills vtex-io-service-paths-and-cdn
```

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

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

## When to use it
- pick a path prefix that fits the data in the response
- explain why a route never receives `vtex_session`
- align `Cache-Control` with how sensitive the payload is
- split public catalog and private account data into separate endpoints
- catch personalized JSON being cached at the edge

## Example prompts
- Check the routes in `service.json` and flag any that return personal data on a public path
- Help me choose between `/_v/segment/` and `/_v/private/` for an endpoint with region-based pricing
- Review the `Cache-Control` headers against what these endpoints actually return

## Similar
- [cdn-caching](https://affpapa.org/en/nevibecode/skills/cdn-caching.md) — skill · 2 installs
- [setup-cdn-optimization](https://affpapa.org/en/nevibecode/commands/setup-cdn-optimization.md) — command · 218 installs
- [cdn-setup](https://affpapa.org/en/nevibecode/skills/cdn-setup.md) — skill · 324 installs
- [netlify-caching](https://affpapa.org/en/nevibecode/skills/netlify-caching.md) — skill · 3100 installs
- [netlify-image-cdn](https://affpapa.org/en/nevibecode/skills/netlify-image-cdn.md) — skill · 3000 installs
- [grpc-service-development](https://affpapa.org/en/nevibecode/skills/grpc-service-development.md) — skill · 527 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