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/

Cross-cutting guidance for designing and reviewing VTEX commerce solutions. Encodes the Well-Architected Commerce pillars: Technical Foundation, Future-proof, and Operational Excellence.

Coding rules and workflow for developing VTEX FastStore storefronts. Covers TypeScript/React conventions, section overrides, BFF extensions, SCSS styling, and CMS sync workflows.

All 9 Payment Provider Protocol endpoints, Payment Provider Framework lifecycle, idempotency patterns, async payment flows, and PCI compliance via the Secure Proxy.

Comprehensive coverage of VTEX IO app development organized into five groups: Foundations, API Exposure, Frontend, Data & Config, and Security & Operations.

¹ Original broader skills retained alongside the newer focused splits.

See tracks/vtex-io/index.md for the full skill table and learning order.

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.

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.

Directory Structure

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
        payment-provider-framework/skill.md
        payment-idempotency/skill.md
        payment-async-flow/skill.md
        payment-pci-security/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

Export Commands

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:kiro

Exports are written to exports/{platform}/ and overwrite existing files. Run export after any skill changes before committing.

Validation

Check all skill files for quality and correctness before exporting:

bun run validate

The validator runs 11 checks on every skill file, split into hard (must pass — block CI) and soft (produce warnings only):

Hard checks (7):

• 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, or FIXME text in prose
• size-bounds — skill files are within acceptable size limits
• track-consistency — the track frontmatter field matches the directory
• globs-format — if present, the globs field is a valid array of glob pattern strings

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