vtex-io-service-paths-and-cdn
VTEX IO service paths and CDN behavior
When this skill applies
Use this skill when you define or change service.json routes for a VTEX IO backend and need the edge (CDN) to pass the right cookies and apply the right caching for that endpoint’s data.
- Choosing between public, segment (
/_v/segment/...), and private (/_v/private/...) path prefixes for a route - Setting
Cache-Control(and related headers) on HTTP responses so public cache behavior matches data scope (anonymous vs segment vs authenticated shopper) - Explaining why a route does not receive
vtex_sessionorvtex_segmentcookies - Troubleshooting CloudFront or edge behavior when cookies are missing (see official troubleshooting)
Do not use this skill for:
- Application-level LRU caches, VBase, or stale-while-revalidate orchestration → use vtex-io-application-performance
- GraphQL field-level
@cacheControlonly → use vtex-io-graphql-api alongside this skill
Decision rules
More from vtexdocs/ai-skills
vtex-io-react-apps
Apply when building React components under react/ or configuring store blocks in store/ for VTEX IO apps. Covers interfaces.json, contentSchemas.json for Site Editor, VTEX Styleguide for admin apps, and css-handles for storefront styling. Use for creating custom storefront components, admin panels, pixel apps, or any frontend development within the VTEX IO react builder ecosystem.
101vtex-io-masterdata
Apply when working with MasterData v2 entities, schemas, or MasterDataClient in VTEX IO apps, or when anyone designing or implementing a solution must scrutinize whether Master Data is the correct storage. The skill prompts hard questions: native Catalog or other VTEX stores, OMS, or an external database may be better; do not default to MD because it is convenient. Covers JSON Schema, CRUD, triggers, search and scroll, schema lifecycle, purchase-path avoidance, single source of truth, and BFF handoffs. Use for justified custom persistence while avoiding the 60-schema limit.
86vtex-io-service-apps
Apply when building backend service apps under node/ in a VTEX IO project or configuring service.json routes. Covers the Service class, middleware functions, ctx.clients pattern, JanusClient, ExternalClient, MasterDataClient, and IOClients registration. Use for implementing backend APIs, event handlers, or integrations that must use @vtex/api clients instead of raw HTTP libraries.
85vtex-io-graphql-api
Apply when working with GraphQL schema files in graphql/ or implementing resolvers in node/resolvers/ for VTEX IO apps. Covers schema.graphql definitions, @cacheControl and @auth directives, custom type definitions, and resolver registration in the Service class. Use for exposing data through GraphQL queries and mutations with proper cache control and authentication enforcement.
83payment-pci-security
Apply when handling credit card data, implementing secureProxyUrl flows, or working with payment security and proxy code. Covers PCI DSS compliance, Secure Proxy card tokenization, sensitive data handling rules, X-PROVIDER-Forward-To header usage, custom token creation, and the constraint that Secure Proxy applies only to card authorization (not post-auth operations like cancel, capture, or refund). Use for any payment connector that processes credit, debit, or co-branded card payments to prevent data breaches and PCI violations.
76vtex-io-app-structure
Apply when creating or modifying manifest.json, service.json, or node/package.json in a VTEX IO app. Covers builders (node, react, graphql, admin, pixel, messages, store), policy declarations, dependencies, peerDependencies, and app lifecycle management. Use for scaffolding new VTEX IO apps, configuring builders, or fixing deployment failures related to app structure and naming conventions.
74