Guía práctica de VTEX Skills + MCP

Nota: Las pruebas de esta guía fueron realizadas en Claude Code. Sin embargo, tanto VTEX Skills como el VTEX Developer MCP son compatibles con Cursor, GitHub Copilot, Codex, Windsurf, Amp, Devin, OpenCode, Kiro y cualquier editor o agente que soporte el estándar MCP o los formatos AGENTS.md / .mdc. Los conceptos y flujos de trabajo aplican igual en todos ellos — solo cambian los comandos de instalación, que están documentados en cada sección.

El problema que resuelve esta guía

Cuando le pides a un agente de IA que te genere código para VTEX, el modelo genérico no sabe:

• Que Master Data tiene un límite de 60 schemas por cuenta.
• Que el endpoint de simulación de fulfillment tiene un timeout forzado de 2.5 segundos.
• Qué patrón de BFF es correcto para servir datos al frontend sin romper el Checkout.
• Cómo está estructurado el Payment Provider Protocol (PPP) y qué endpoints son obligatorios.
• Qué hace el useProduct hook de FastStore vs. el useProductQuery.

El resultado: código que compila pero rompe en producción, o que viola restricciones de arquitectura que descubres semanas después.

La solución son dos herramientas oficiales de VTEX que trabajan en capas:

Usadas juntas, tu agente sabe cómo trabaja VTEX (Skills) y puede verificar los detalles exactos (MCP) sin que tú tengas que pegar documentación manualmente en el chat.

Fase 1: Instalación y Configuración en Claude Code

Prerrequisitos

node --version  # Necesitas Node.js 18+
npx --version   # Viene incluido con Node

Paso 1: Instalar VTEX Skills en tu proyecto

Navega a la raíz de tu proyecto VTEX y ejecuta:

npx skills add vtex/skills

El CLI descarga el repositorio de skills desde https://github.com/vtex/skills.git, encuentra las 39 skills disponibles y arranca el proceso de selección interactivo:

Selección de skills: Usa espacio para marcar/desmarcar cada skill. Las que tienen ■ quedan seleccionadas. Puedes filtrar por nombre escribiendo directamente:

Selección de agentes: El CLI detecta automáticamente los agentes instalados en tu máquina. Agrupa los agentes en dos categorías: Universal (siempre incluidos vía .agents/skills) y Additional agents donde aparecen Claude Code, Augment, IBM Bob, OpenClaw y otros. Claude Code se instala como symlink en .claude/skills:

Scope de instalación: Elige Project para que los archivos queden en el repositorio y todo el equipo los comparta, o Global para instalación personal en tu máquina:

Security Risk Assessment: Antes de proceder, el CLI audita cada skill con tres herramientas (Gen, Socket, Snyk) y muestra el resultado. Todas las skills califican como Safe con 0 alerts. Dos skills (vtex-io-http-routes y vtex-io-service-apps) tienen clasificación Med Risk en Snyk — esto es por patrones de rutas HTTP, no por código malicioso:

Al confirmar, el CLI completa la instalación y crea la estructura de archivos en .claude/skills/:

Cada carpeta contiene un SKILL.md con el contenido de esa skill. Estos archivos son los que el agente lee automáticamente al inicio de cada sesión.

¿Qué tracks instalar? Como referencia rápida:

Para instalar todo sin prompts interactivos:

npx skills add vtex/skills --all

Para ver qué skills están disponibles antes de instalar:

npx skills add vtex/skills --list

Paso 2: Configurar el VTEX Developer MCP en Claude Code

Ejecuta este comando en tu terminal (una sola vez por máquina, o por proyecto):

claude mcp add vtex-developer -- npx -y @vtex/developer-mcp

Alternativamente, crea un archivo .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "vtex-developer": {
      "command": "npx",
      "args": ["-y", "@vtex/developer-mcp"]
    }
  }
}

Tip: El archivo .mcp.json en la raíz del proyecto permite que todo el equipo comparta la misma configuración del MCP. Súbelo al repositorio.

Paso 3: Verificar la instalación

Abre Claude Code y ejecuta en el chat:

Search VTEX documentation for "Payment Provider Protocol mandatory endpoints"

Si el MCP está activo, verás que Claude consulta la documentación en tiempo real. Si las Skills están activas, las respuestas incluirán restricciones específicas de VTEX (como los headers requeridos en PPP) sin que tú las hayas mencionado.

Bonus: Invocar Skills directamente con comandos /

Aunque Claude Code y otros editores cargan las Skills automáticamente desde .claude/ o el AGENTS.md al inicio de cada sesión, puedes invocar cualquier skill manualmente usando su nombre como comando / directamente en el chat.

Esto es útil cuando quieres cargar el contexto de una skill específica en medio de una tarea, sin que el agente tenga que inferir cuál aplica.

Cómo se ve en Claude Code

Escribe /vtex en el chat y el editor te muestra el listado completo de skills disponibles con su descripción:

Cuándo usar el comando / en lugar de dejar que el agente cargue automáticamente

Ejemplo de uso en la práctica

En lugar de escribir un prompt largo explicando cómo funcionan las rutas HTTP en VTEX IO:

/vtex-io-http-routes

Ahora crea un endpoint POST /notify que reciba un webhook de un
proveedor externo y lo procese en el servicio Node.js de la app
`my-integration`. Incluye validación de firma HMAC en el middleware.

El agente ya tiene cargado el patrón correcto de service.json, la estructura de handlers y las restricciones de seguridad — sin que tú tengas que describirlas.

Skills disponibles por track (referencia de comandos /)

Las 39 skills están organizadas en 6 tracks. Estos son los nombres exactos tal como aparecen en el CLI:

Architecture (1 skill)

/architecture-well-architected-commerce   → Scoping, review y documentación de arquitectura cross-cutting

FastStore (1 skill)

/faststore-storefront                     → Implementación de storefronts con FastStore

Headless Front-End Development (4 skills)

/headless-bff-architecture                → Diseño o modificación de un BFF (Backend-for-Frontend)
/headless-caching-strategy                → Lógica de caché, configuración de CDN
/headless-checkout-proxy                  → Proxy de Checkout en arquitecturas headless
/headless-intelligent-search              → Integración con Intelligent Search API

Marketplace Integration (4 skills)

/marketplace-catalog-sync                 → Sincronización de catálogo SKU
/marketplace-fulfillment                  → Simulación de fulfillment y timeouts
/marketplace-order-hook                   → Hooks de órdenes en marketplace
/marketplace-rate-limiting                → Rate limiting en integraciones de marketplace

Payment Connector Development (5 skills)

/payment-async-flow                       → Flujos de pago asíncronos
/payment-idempotency                      → Patrón de idempotency con requestId
/payment-pci-security                     → Secure Proxy y compliance PCI
/payment-provider-framework               → Lifecycle del framework de Payment Provider
/payment-provider-protocol                → Endpoints del Payment Provider Protocol (PPP)

Custom VTEX IO Apps (24 skills)

/vtex-io-admin-react                      → Interfaces React del Admin Builder
/vtex-io-app-contract                     → Definición y cambios del contrato de una app IO
/vtex-io-app-settings                     → Definición, validación y consumo de settings
/vtex-io-application-performance          → Performance en servicios Node o .NET
/vtex-io-auth-and-policies                → Permisos y autorizaciones
/vtex-io-auth-tokens-and-context          → Tokens de autenticación VTEX IO y contexto
/vtex-io-client-integration               → Diseño e implementación de clientes backend IO
/vtex-io-data-access-patterns             → Estrategia de acceso a datos en apps IO
/vtex-io-events-and-workers               → Procesos asíncronos, eventos y workers
/vtex-io-graphql-api                      → Schemas GraphQL y resolvers en node/resolvers/
/vtex-io-http-routes                      → Endpoints HTTP en servicios backend IO
/vtex-io-masterdata                       → Master Data v2, schemas, MasterDataClient
/vtex-io-masterdata-strategy              → Decisión de cuándo y cómo usar Master Data
/vtex-io-messages-and-i18n                → Localización y copy traducido
/vtex-io-observability-and-ops            → Observabilidad, logs y troubleshooting
/vtex-io-react-apps                       → Componentes React en react/ y bloques en store/
/vtex-io-render-runtime-and-blocks        → Conexión de React con Store Framework
/vtex-io-security-boundaries              → Límites de seguridad en apps IO
/vtex-io-service-apps                     → Apps de servicio backend bajo node/
/vtex-io-service-configuration-apps       → Apps de configuración, service.json y rutas públicas
/vtex-io-service-paths-and-cdn            → Rutas de service.json y configuración de CDN
/vtex-io-service-runtime                  → Runtime de servicios IO (diseño e implementación)
/vtex-io-session-apps                     → Session transform apps (vtex.session)
/vtex-io-testing                          → Testing de apps VTEX IO

Nota: Escribe /vtex en Claude Code para ver el listado en tiempo real con los nombres exactos de tu instalación. La versión actual del CLI es skills@1.5.1.

Fase 2: Flujo de Trabajo Diario

El modelo mental correcto

Piensa en las dos herramientas como capas de conocimiento:

┌─────────────────────────────────────────────┐
│           TU PROMPT                         │
├─────────────────────────────────────────────┤
│   VTEX Skills (contexto persistente)        │
│   • Patrones de arquitectura                │
│   • Límites de plataforma                   │
│   • Anti-patrones conocidos                 │
├─────────────────────────────────────────────┤
│   VTEX Developer MCP (consulta dinámica)    │
│   • Specs exactas de endpoints              │
│   • Documentación actualizada               │
│   • Parámetros de API                       │
└─────────────────────────────────────────────┘

Cuándo confiar en las Skills (contexto persistente)

Úsalas como base para todas las tareas VTEX. El agente automáticamente aplica:

• Estructura correcta de manifests (manifest.json, service.json)
• Políticas de seguridad (outboundAccess, readerAccess)
• Patrones de BFF obligatorios
• Límites de Master Data
• Timeouts de simulación de fulfillment

No necesitas mencionar estas restricciones en tu prompt. Las Skills ya las cargan.

Cuándo pedir al agente que use el MCP

Pide explícitamente que use el MCP cuando necesites:

• Specs exactas de un endpoint que podrían haber cambiado recientemente
• Detalles de un campo específico en un request/response body
• Confirmar si una feature existe en la versión actual de la documentación
• Resolver un error 4xx/5xx cuya causa no está clara

Cómo pedirlo en tu prompt:

Search VTEX documentation for [tema]
Fetch the full guide at [URL específica]
Search for API endpoints related to [funcionalidad]
Get the full specification for the [Nombre] endpoint

Cuándo NO necesitas el MCP

• Patrones de arquitectura generales (cubiertos por Skills)
• Estructura de proyectos IO (cubierta por Skills)
• Código boilerplate de componentes estándar (el modelo lo conoce)
• Tareas de refactoring o testing que no involucran APIs nuevas

Fase 3: Prompts de Alto Rendimiento — Ejemplos Prácticos

La estructura de un prompt efectivo para desarrollo VTEX con estas herramientas:

[Contexto del proyecto] + [Tarea específica] + [Restricciones conocidas] + [Output esperado]

Ejemplo 1: App VTEX IO con Master Data y GraphQL

Soy el developer de una app VTEX IO llamada `store-wishlist`.
Necesito crear una entidad en Master Data v2 para guardar wishlists
de usuarios, con las siguientes propiedades:
- userId (string, requerido, indexed)
- productIds (array de strings)
- createdAt (timestamp)

Genera:
1. El schema JSON para la entidad en Master Data v2
2. Un GraphQL resolver en Node.js que consulte esta entidad
   usando el VtexCommerce client
3. El fragmento de `manifest.json` con los policies necesarios

Antes de generar el código, busca en la documentación:
search_documentation "Master Data v2 schema creation"

Por qué funciona: Las Skills aplican el límite de 60 schemas y los patrones correctos de policies. El MCP verifica el formato exacto del schema JSON actual.

Ejemplo 2: Override de componente en FastStore

Estoy implementando un override del componente `ProductTitle` en
FastStore para agregar un badge de "Nuevo" cuando el producto
fue lanzado hace menos de 30 días.

El campo de fecha de lanzamiento está en el campo customizado
`releaseDate` del catálogo VTEX.

Genera:
1. El override correcto en `src/components/overrides/`
2. El fragmento de GraphQL necesario para traer `releaseDate`
   desde la query del PDP
3. El uso correcto del hook de FastStore para acceder a los
   datos del producto sin romper el SSR

Antes de generar, busca:
search_documentation "FastStore product override"

Por qué funciona: Las Skills conocen la API de Overrides y sus restricciones (no puedes hacer overrides de componentes de layout). El MCP confirma la estructura actual de la query del PDP.

Ejemplo 3: Payment Provider Protocol completo

Necesito implementar los endpoints obligatorios del Payment
Provider Protocol (PPP) para integrar con el gateway "PagoDirecto".

El gateway usa:
- Autenticación: API Key en header `X-PagoDirecto-Key`
- Webhooks para notificaciones asíncronas
- Soporte para cancelación parcial

Genera:
1. Los 5 endpoints obligatorios del PPP con su estructura
   correcta de request/response
2. El middleware de idempotency usando el campo `requestId`
3. La lógica de manejo del callback asíncrono
4. El `manifest.json` con la sección `payment` configurada

Antes de generar, busca:
fetch_document "https://developers.vtex.com/docs/guides/payments-integration-payment-provider-protocol"

Por qué funciona: Las Skills conocen el protocolo PPP, los headers de Secure Proxy requeridos para PCI, y el patrón de idempotency. El MCP trae la spec actualizada con todos los campos obligatorios.

Estrategias para Mantener Todo Actualizado

Actualizar las Skills

Las Skills se versionan junto con la documentación oficial de VTEX. Para actualizar:

# Siempre trae la última versión
npx skills add vtex/skills

# Para CI/CD: fijar una versión específica
npx skills add vtex/skills@1.2.0

Recomendación: Agrega la actualización de Skills como parte de tu proceso de onboarding de proyecto. Inclúyela en el README.md:

## Setup de desarrollo

1. `npm install`
2. `npx skills add vtex/skills --all`  ← Agregar esto
3. Configurar `.mcp.json` con el VTEX Developer MCP

Estrategia de versioning en equipo

Sube el .mcp.json al repositorio. Para las Skills, dado que los archivos se colocan en directorios del agente (no en el repo), documenta en el README.md el comando exacto con versión:

# En README.md o CONTRIBUTING.md
npx skills add vtex/skills@<version-del-equipo>

Revisa el changelog de releases antes de actualizar en proyectos en producción.

Evitar Errores Comunes de Arquitectura

Estos son los errores más frecuentes que las Skills previenen automáticamente, y cómo el MCP ayuda a resolverlos:

Error 1: BFF mal estructurado

Síntoma: El frontend llama directamente a APIs de VTEX desde el browser, exponiendo credenciales o rompiendo CORS.

Cómo lo previene: El track "Headless Front-End Development" incluye el patrón correcto de BFF. El agente automáticamente genera el proxy en Node.js con las cabeceras correctas.

Prompt de rescate:

search_documentation "BFF pattern VTEX headless checkout proxy"

Error 2: Superar el límite de 60 schemas en Master Data

Síntoma: Error 400 al crear una nueva entidad. La cuenta ya tiene 60 schemas.

Cómo lo previene: Las Skills advierten sobre este límite en cualquier tarea que involucre Master Data. El agente sugerirá reutilizar una entidad existente o migrar a una solución alternativa (VBase, por ejemplo).

Error 3: PPP sin idempotency

Síntoma: El gateway procesa pagos duplicados porque VTEX reintenta el request.

Cómo lo previene: El track de Payment incluye la lógica de idempotency como parte del boilerplate generado. No tienes que recordarlo.

Error 4: Timeout en simulación de fulfillment

Síntoma: El carrito falla silenciosamente. El endpoint de simulación supera los 2.5s.

Cómo lo previene: Las Skills documentan este límite. El agente genera la lógica con cacheo y respuestas tempranas para mantenerse bajo el threshold.

Error 5: Override de FastStore rompiendo SSR

Síntoma: El componente funciona en desarrollo pero falla en producción con un error de hidratación.

Cómo lo previene: El track de FastStore incluye el patrón correcto para overrides con soporte SSR. El agente no usará window ni document directamente en el override.

Referencia Rápida: Comandos Esenciales

# Instalación inicial
npx skills add vtex/skills --all
claude mcp add vtex-developer -- npx -y @vtex/developer-mcp

# Actualización de skills
npx skills add vtex/skills

# Ver skills disponibles
npx skills add vtex/skills --list

# Probar el MCP manualmente
npx -y @vtex/developer-mcp

Las 4 herramientas del MCP que puedes pedir en tus prompts

Ahorra tokens con Skills y MCP

Uno de los beneficios menos obvios pero más importantes de este setup es el ahorro de tokens. Cada vez que tú pegas documentación manualmente en el prompt, explicas cómo funciona una API, o corriges al agente porque generó código que no sigue las reglas de VTEX, estás consumiendo tokens — y en Claude Code, eso se traduce directamente en el medidor de uso de tu sesión. Las Skills eliminan esa fricción: el contexto ya está cargado antes de que escribas tu primer mensaje, así que el agente no necesita que se lo expliques ni tú necesitas gastar tokens corrigiéndolo. El MCP complementa esto de forma quirúrgica — en lugar de pegar una página entera de documentación en el chat, el agente hace una consulta puntual y trae solo lo que necesita. El resultado es que tareas que antes requerían múltiples rondas de corrección y contexto manual — y agotaban el 50-60% de la sesión — ahora se resuelven en una sola pasada consumiendo una fracción de ese uso. Menos tokens gastados en setup significa más tokens disponibles para el trabajo real.

TL;DR para el equipo

1. Instala las Skills una vez por proyecto con npx skills add vtex/skills --all. Súbelas al proceso de setup del equipo.
2. El .mcp.json va en el repo. Así todos tienen el MCP activo automáticamente.
3. No repitas restricciones de plataforma en tus prompts: las Skills ya las tienen. Enfócate en describir qué quieres construir.
4. Pide al agente que use el MCP cuando necesites specs de API exactas o documentación actualizada.
5. Actualiza las Skills cuando salga una versión nueva, especialmente antes de empezar un nuevo proyecto.

Con este setup, el agente conoce VTEX como un senior del equipo de plataforma — y puede verificar los detalles cuando los necesita.

Documento basado en la documentación oficial de VTEX Skills y VTEX Developer MCP. Última revisión: Abril 2026.