# vtex-io-events-and-workers

Guides the agent in writing VTEX IO event handlers and workers that survive duplicate delivery. Useful when slow work should leave your HTTP routes.

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

## What it does

This skill steers an agent through async processing in VTEX IO services: event handlers, workers and background jobs. Anything slow, retry-prone or unnecessary for an HTTP response gets moved out of the route. The starting assumption is that the same event can arrive more than once.

The rules come with TypeScript examples. A handler that writes data or calls an external API without first checking whether the job is done counts as a bug, and the skill tells the agent to stop and fix it. Processing markers live in VBase or Master Data. Input comes from the event body, never from route params or request headers. Failures are recorded and rethrown rather than swallowed. Events and workers are declared in `service.json`, and publishing events often requires the `colossus-fire-event` policy in `manifest.json`.

The suggested layout is `node/events/` holding `index.ts`, `catalog.ts` and `orders.ts`, plus `node/workers/sync.ts`. For batches, status is stored per item, so one bad element doesn't hide the rest. HTTP route contracts, GraphQL schemas, app policy decisions and client construction are out of scope.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills vtex-io-events-and-workers
```

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

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

## When to use it
- move a heavy catalog sync out of an HTTP route
- stop a partner from receiving the same order twice after a redelivered event
- record status per batch item to see which ones failed
- keep processed markers in VBase or Master Data
- publish events to other apps instead of hand-rolled HTTP callbacks

## Example prompts
- Write a VTEX IO handler for the order-created event so a redelivery doesn't send the order to the partner again
- Move the catalog sync out of the route into a worker and register it in `service.json`
- Review my handlers in `node/events/` for idempotency and swallowed errors

## 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