40 AI agent skills for VTEX platform development — one source, six export formats.
Quick Start • Tracks • Platforms • Contributing
If you have the GitHub CLI installed, this is the fastest path. It auto-detects which agents you have configured, supports version pinning, and provides gh skill update to stay current.
# Browse and install skills interactively
gh skill install vtex/skills
# Install a specific skill
gh skill install vtex/skills payment-provider-protocol
# Target a specific agent explicitly
gh skill install vtex/skills payment-provider-protocol --agent claude-code
# Pin to a release for reproducibility
gh skill install vtex/skills payment-provider-protocol --pin v1.9.0
# Keep all installed skills up to date
gh skill update --allSkills are installed to .agents/skills/ at project scope by default — shared automatically across GitHub Copilot, Cursor, Claude Code, Codex, OpenCode, Windsurf, and 40+ other agents. Use --scope user to install globally instead.
Works on any machine with Node.js. Handles bulk installs and is CI-friendly:
npx skills add vtex/skillsUse --list to preview available skills before installing, --all --yes to install everything non-interactively, or --agent <name> to target a specific tool.
Install directly via curl, manual copy, or file upload — no CLI needed
curl -sL https://github.com/vtex/skills/releases/latest/download/agents-md.tar.gz | tar xz -C your-project/This places a root AGENTS.md with links to per-track files in subdirectories. Most AI coding tools discover and follow these instructions automatically.
mkdir -p your-project/.cursor/rules
curl -sL https://github.com/vtex/skills/releases/latest/download/cursor-rules.tar.gz | tar xz -C your-project/.cursor/rules/Each .mdc file includes glob patterns that auto-attach the rule when you open matching files. Per-track composites (e.g., faststore-all.mdc) are also available.
mkdir -p your-project/.github
curl -sL https://github.com/vtex/skills/releases/latest/download/copilot-instructions.tar.gz | tar xz -C your-project/.github/Per-track files are available in exports/copilot/ if you only need a subset.
Upload files from exports/claude/ as project knowledge in your Claude Project settings. Use individual skill files for focused context, or per-track composites (e.g., faststore.md) for broader coverage.
curl -sL https://github.com/vtex/skills/releases/latest/download/opencode-skills.tar.gz | tar xz -C ~/.config/opencode/skills/Each skill becomes a directory with a SKILL.md file. OpenCode discovers them automatically and makes them available as loadable skills in your sessions.
git clone https://github.com/vtex/skills.git
cd skills
# AGENTS.md
cp -r exports/agents-md/. /path/to/your-project/
# Cursor
mkdir -p /path/to/your-project/.cursor/rules
cp exports/cursor/*.mdc /path/to/your-project/.cursor/rules/
# Copilot
cp exports/copilot/copilot-instructions.md /path/to/your-project/.github/copilot-instructions.md
# OpenCode
cp -r exports/opencode/. ~/.config/opencode/skills/- AI assistants don't know VTEX-specific patterns. The Overrides API, PPP endpoints, BFF requirements, and MasterData schema limits aren't in any LLM's training data at the depth you need. These skills fill that gap.
- Real constraints, not generic advice. PCI compliance via the Secure Proxy, idempotency requirements on payment endpoints, the 2.5s fulfillment simulation timeout, the 60-schema MasterData limit — these are the details that prevent costly mistakes in production.
- One source, six platforms. Skills are authored once in a canonical Markdown format and exported automatically. No manual sync, no drift between tools.
- Built from official VTEX documentation. Not generic LLM knowledge. Every constraint has a source, a detection pattern, and paired correct/wrong code examples.
| Platform | Format | Auto-detection | Layout |
|---|---|---|---|
| AGENTS.md | Markdown | ✅ Native in 7+ tools | 1 root file + 1 per track |
| Cursor | .mdc rules |
✅ Glob + description | 1 per skill + per-track composites |
| GitHub Copilot | Instructions | ✅ Auto-loaded | 1 master file + 1 per track |
| Claude Projects | Knowledge files | Manual upload | 1 per skill + per-track composites |
| OpenCode | SKILL.md |
✅ Auto-discovered | 1 directory per skill |
| Kiro | POWER.md + steering |
✅ Auto-discovered | 1 POWER.md + per-skill steering files |
Track 1: Well-Architected Commerce & Solution Architecture — 1 skill for cross-cutting architecture
Cross-cutting guidance for designing and reviewing VTEX commerce solutions. Encodes the Well-Architected Commerce pillars: Technical Foundation, Future-proof, and Operational Excellence.
| Skill | Description |
|---|---|
architecture-well-architected-commerce |
Solution design, architecture reviews, and RFP-level technical structure |
Track 2: FastStore Implementation — 1 skill for storefront development
Coding rules and workflow for developing VTEX FastStore storefronts. Covers TypeScript/React conventions, section overrides, BFF extensions, SCSS styling, and CMS sync workflows.
| Skill | Description |
|---|---|
faststore-storefront |
Core coding rules, conventions, and development workflow for FastStore storefronts |
Track 3: Payment Connector Development — 5 skills for PPP integration
All 9 Payment Provider Protocol endpoints, Payment Provider Framework lifecycle, idempotency patterns, async payment flows, and PCI compliance via the Secure Proxy.
| Skill | Description |
|---|---|
payment-provider-protocol |
All 9 PPP endpoints: 6 payment flow + 3 configuration flow |
payment-provider-framework |
PPF lifecycle, configuration endpoints, retry and notification patterns |
payment-idempotency |
paymentId and requestId idempotency, duplicate prevention |
payment-async-flow |
Async approval, callback URLs, and the 7-day retry window |
payment-pci-security |
Secure Proxy, card tokenization, and PCI constraint enforcement |
Track 4: Custom VTEX IO Apps — 24 skills for IO app development
Comprehensive coverage of VTEX IO app development organized into five groups: Foundations, API Exposure, Frontend, Data & Config, and Security & Operations.
| Group | Skills |
|---|---|
| Foundations | vtex-io-app-contract, vtex-io-service-runtime, vtex-io-client-integration, vtex-io-service-apps¹ |
| API Exposure | vtex-io-graphql-api, vtex-io-http-routes, vtex-io-events-and-workers |
| Frontend | vtex-io-storefront-react, vtex-io-admin-react, vtex-io-render-runtime-and-blocks, vtex-io-messages-and-i18n, vtex-io-react-apps¹ |
| Data & Config | vtex-io-app-settings, vtex-io-service-configuration-apps, vtex-io-masterdata-strategy, vtex-io-data-access-patterns, vtex-io-masterdata¹, vtex-io-service-paths-and-cdn, vtex-io-application-performance, vtex-io-session-apps |
| Security & Ops | vtex-io-auth-tokens-and-context, vtex-io-auth-and-policies, vtex-io-security-boundaries, vtex-io-observability-and-ops |
¹ Original broader skills retained alongside the newer focused splits.
See tracks/vtex-io/index.md for the full skill table and learning order.
Track 5: Marketplace Integration — 4 skills for marketplace connectors
SKU catalog sync, order hooks, fulfillment simulation, and rate limiting for marketplace connectors. Covers the Change Notification flow, Feed v3 vs Hook tradeoffs, and invoice/tracking patterns.
| Skill | Description |
|---|---|
marketplace-catalog-sync |
Change Notification entry point, SKU suggestion lifecycle |
marketplace-order-hook |
Feed v3 (pull) vs Hook (push), filter types, commit patterns |
marketplace-fulfillment |
External Seller protocol, simulation, orders, invoice and tracking |
marketplace-rate-limiting |
429 handling, exponential backoff, circuit breaker patterns |
Track 6: Headless Front-End Development — 4 skills for headless storefronts
BFF architecture, Intelligent Search API, checkout proxy patterns, and caching strategy for headless VTEX storefronts. Covers why a BFF is mandatory and which APIs can never be called from the browser.
| Skill | Description |
|---|---|
headless-bff-architecture |
BFF layer design, auth proxy, and API key protection |
headless-intelligent-search |
Search, facets, autocomplete, and Search Events API |
headless-checkout-proxy |
Checkout API proxying, session cookies, and the 5-minute order window |
headless-caching-strategy |
TTL rules, stale-while-revalidate, and what must never be cached |
Track 7: Sales App Extension Development — 1 skill for Sales App extensions
Complete 6-step workflow for building VTEX Sales App extensions. Covers extension points (cart, PDP, menu), React hooks (useCart, usePDP, useCartItem, useCurrentUser, useExtension), TypeScript types, secure API integration patterns, code generation, validation, and deployment.
| Skill | Description |
|---|---|
sales-app-extensibility |
Full lifecycle of Sales App extension development — prerequisites, discovery, code generation, validation, and deployment |
This repository is an Open Plugin — a portable, platform-agnostic skill pack that any AI coding tool can discover and install.
rules/*.mdc # Cursor rules (auto-discovered)
skills/*/SKILL.md # Agent skills (auto-discovered)
.cursor-plugin/plugin.json # Cursor plugin manifest
.plugin/plugin.json # Vendor-neutral plugin manifest
Compatible tools (Cursor, Claude Code, and others implementing the Open Plugins spec) can install this repo directly as a plugin. The rules/ and skills/ directories at the repo root follow the standard layout, and the manifests provide metadata for discovery.
Directory structure, export commands, and validation
vtex_skills/
_templates/
skill-template.md # Canonical template for new skills
tracks/ # SOURCE — edit skill files here
architecture/
index.md
skills/
architecture-well-architected-commerce/skill.md
faststore/
index.md
skills/
faststore-storefront/skill.md
headless/
index.md
skills/
headless-bff-architecture/skill.md
headless-intelligent-search/skill.md
headless-checkout-proxy/skill.md
headless-caching-strategy/skill.md
marketplace/
index.md
skills/
marketplace-catalog-sync/skill.md
marketplace-order-hook/skill.md
marketplace-fulfillment/skill.md
marketplace-rate-limiting/skill.md
payment/
index.md
skills/
payment-provider-protocol/skill.md
...
sales-app/
index.md
skills/
sales-app-extensibility/skill.md
vtex-io/
index.md
skills/
vtex-io-app-contract/skill.md
vtex-io-service-runtime/skill.md
vtex-io-client-integration/skill.md
... (24 skills — see tracks/vtex-io/index.md)
exports/ # auto-generated — do not edit
agents-md/ # AGENTS.md format
claude/ # Claude Projects format
copilot/ # GitHub Copilot format
cursor/ # Cursor .mdc format
kiro/ # Kiro Power + steering format
opencode/ # OpenCode SKILL.md format
skills/ # auto-generated — do not edit (OpenCode export)
rules/ # auto-generated — do not edit (Cursor export)
scripts/
export.ts # Generates all platform exports
validate.ts # Validates all skill files
package.json
tsconfig.json
Generate platform exports from the source skill files:
# Export to all platforms
bun run export
# Export to a specific platform
bun run export:cursor
bun run export:copilot
bun run export:claude
bun run export:agents-md
bun run export:opencode
bun run export:kiroExports are written to exports/{platform}/ and overwrite existing files. Run export after any skill changes before committing.
Check all skill files for quality and correctness before exporting:
bun run validateThe validator runs 13 checks on every skill file, split into hard (must pass — block CI) and soft (produce warnings only):
Hard checks (9):
- yaml-validity — frontmatter parses without errors, has required fields (name, description, track, tags)
- description-quality — description is at least 20 words
- code-block-annotations — all opening code fences have a language annotation
- no-placeholders — no
TBD,TODO, orFIXMEtext in prose - size-bounds — skill files are within acceptable size limits
- track-consistency — the
trackfrontmatter field matches the directory - globs-format — if present, the
globsfield is a valid array of glob pattern strings - filename-casing — the file is named
skill.md(lowercase) - companion-links — all relative links in the skill file resolve to existing files
Soft checks (4) — produce warnings but do not block CI:
- required-sections — recommended H2 sections present (decision-oriented template)
- detection-patterns — constraints include a Detection field
- paired-examples — constraints have both a Correct and Wrong example
- url-format — VTEX doc links use the correct domain format
See CONTRIBUTING.md for a complete guide on adding skills, tracks, and export platforms.
See LICENSE for details.