vtex-io-service-apps — Claude Code skill: install and usage
Guides backend service development under node/ in VTEX IO apps. Configures routes, middleware chains, and @vtex/api clients for background tasks or APIs.
npx skills add vtex/skills --skill vtex-io-service-apps -a claude-codeWhat vtex-io-service-apps does
This skill configures the backend entry point in node/index.ts with the Service class. It connects HTTP routes from service.json, event handlers, and GraphQL resolvers to the ctx execution context.
Network requests rely on specialized classes. Use JanusClient for internal VTEX gateways and ExternalClient for third-party endpoints. Queries to Master Data v2 go through MasterDataClient. Custom connectors register inside an IOClients class, where getOrSet instantiates them on first access.
Direct calls via fetch or axios fail because the platform firewall drops raw outbound connections. All traffic must pass through @vtex/api clients. Instantiating client classes with new is also prohibited; handlers must access them via ctx.clients to keep authentication tokens and metric tracking intact.
What it helps with
- Define backend routes and middleware chains in
service.json - Integrate third-party REST services with
ExternalClient - Register custom API connectors inside
IOClientsusing lazy loading - Replace forbidden
fetchoraxioscalls with@vtex/apiwrappers
Example prompts for the agent
- Write a middleware handler that fetches catalog items through
ctx.clients.catalog - Create an
ExternalClientsubclass to query an external shipping API with custom headers - Set up the
node/index.tsfile with typedServiceconfiguration and client declarations
How to install vtex-io-service-apps
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -a claude-code2Manually: put the files in place
~/.claude/skills/vtex-io-service-apps/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vtex-io-service-apps/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -a codex2Manually: put the files in place
.agents/skills/vtex-io-service-apps/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -a cursor2Manually: put the files in place
.cursor/skills/vtex-io-service-apps/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills vtex-io-service-apps2Manually: put the files in place
.github/skills/vtex-io-service-apps/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-service-appsManually: put the files in place
.devin/skills/vtex-io-service-apps/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-service-apps -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-service-apps
How do I install vtex-io-service-apps in Claude Code?
Run npx skills add vtex/skills --skill vtex-io-service-apps -a claude-code. This copies the skill file to ~/.claude/skills/vtex-io-service-apps/SKILL.md.
What does the vtex-io-service-apps skill do?
It provides architecture patterns for VTEX IO Node.js services. The skill directs assistants to build middlewares, lifecycle handlers, and @vtex/api clients according to platform requirements.
Why are axios and fetch prohibited in VTEX IO services?
Platform infrastructure firewalls unmanaged outbound traffic, blocking direct HTTP libraries. Official @vtex/api clients handle automatic token injection, request retries, and latency tracking.
