vtex-io-events-and-workers — Claude Code skill
Guides the agent in writing VTEX IO event handlers and workers that survive duplicate delivery. Useful when slow work should leave your HTTP routes.
npx skills add vtex/skills --skill vtex-io-events-and-workers -a claude-codeWhat vtex-io-events-and-workers 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.
What it helps with
- 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 for the agent
- 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
How to install vtex-io-events-and-workers
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-events-and-workers -a claude-code2Manually: put the files in place
~/.claude/skills/vtex-io-events-and-workers/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vtex-io-events-and-workers/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-events-and-workers -a codex2Manually: put the files in place
.agents/skills/vtex-io-events-and-workers/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-events-and-workers -a cursor2Manually: put the files in place
.cursor/skills/vtex-io-events-and-workers/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills vtex-io-events-and-workers2Manually: put the files in place
.github/skills/vtex-io-events-and-workers/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-events-and-workers -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-events-and-workersManually: put the files in place
.devin/skills/vtex-io-events-and-workers/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-events-and-workers -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about vtex-io-events-and-workers
How do I install vtex-io-events-and-workers in Claude Code?
Run npx skills add vtex/skills --skill vtex-io-events-and-workers -a claude-code. The skill file ends up at ~/.claude/skills/vtex-io-events-and-workers/SKILL.md.
What does vtex-io-events-and-workers do?
It tells the agent how to build VTEX IO event handlers and workers that tolerate duplicates, record failures and don't depend on HTTP request data. Expensive work is moved out of routes.
Does publishing events need a policy in manifest.json?
An app that publishes through the VTEX IO event bus often needs the colossus-fire-event policy. Other policies are added only when the app uses the protected resources they cover.
