vtex-io-http-routes — Claude Code skill: HTTP routes in VTEX IO

What vtex-io-http-routes 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.