# vtex-io-http-routes

Guides the design of HTTP endpoints in a VTEX IO backend service: route boundaries, middleware chains, request validation and response shape.

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

## What it does

The skill kicks in when a VTEX IO service has to expose HTTP endpoints through `service.json` routes and handlers under `node/`. It covers where a route boundary sits, how to compose middleware, and how to describe params, query values, headers and body shape close to the handler.

Inside are decision rules and hard constraints with code samples. A handler must keep the contract explicit: if it delegates right away without validating required params, the skill says stop and write the contract first. Repeated signature checks or request normalization belong in middleware, not copied across handlers. Long loops and batch imports in a route are a signal to move the work to an async flow and answer `202`.

There is a recommended layout: `node/routes/` grouped by domain, such as `orders.ts` and `webhooks.ts`, with `node/middlewares/` alongside. A public route counts as an external contract, so widening one to `public` without reviewing validation and auth is a bad idea. The skill is not for GraphQL APIs, app policies in `manifest.json`, or runtime tuning — it will not help there.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

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

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

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

## When to use it
- spell out a webhook contract for a partner
- move a signature check into middleware
- split a synchronous route from background processing
- align status codes and response shape across a route family
- group route files by bounded domain

## Example prompts
- add a partner callback webhook to service.json and a handler in node/routes
- check that the order handler validates params before calling the client
- extract the x-signature check into middleware and wire it into the order routes

## Similar
- [convex-http-actions](https://affpapa.org/en/nevibecode/skills/convex-http-actions.md) — skill · 2700 installs
- [extension-http-outcalls](https://affpapa.org/en/nevibecode/skills/extension-http-outcalls.md) — skill · 28100 installs
- [flutter-use-http-package](https://affpapa.org/en/nevibecode/skills/flutter-use-http-package.md) — skill · 36100 installs
- [http-parameter-pollution](https://affpapa.org/en/nevibecode/skills/http-parameter-pollution.md) — skill · 3600 installs
- [http-host-header-attacks](https://affpapa.org/en/nevibecode/skills/http-host-header-attacks.md) — skill · 3600 installs
- [nodejs-express-server](https://affpapa.org/en/nevibecode/skills/nodejs-express-server.md) — skill · 3300 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