{ "markdown": "

\n \"VTEX\n

\n\n

VTEX Skills

\n

\n 40 AI agent skills for VTEX platform development — one source, six export formats.\n

\n

\n Quick Start •\n Tracks •\n Platforms •\n Contributing\n

\n

\n \"40\n \"7\n \"6\n \"License\"\n \"Build\"\n

\n\n---\n\n## Quick Start\n\n### GitHub CLI (Recommended — requires `gh` v2.90.0+)\n\nIf you have the [GitHub CLI](https://cli.github.com/) 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.\n\n```bash\n# Browse and install skills interactively\ngh skill install vtex/skills\n\n# Install a specific skill\ngh skill install vtex/skills payment-provider-protocol\n\n# Target a specific agent explicitly\ngh skill install vtex/skills payment-provider-protocol --agent claude-code\n\n# Pin to a release for reproducibility\ngh skill install vtex/skills payment-provider-protocol --pin v1.9.0\n\n# Keep all installed skills up to date\ngh skill update --all\n```\n\nSkills 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](https://cli.github.com/manual/gh_skill_install). Use `--scope user` to install globally instead.\n\n### npx (No GitHub CLI required)\n\nWorks on any machine with Node.js. Handles bulk installs and is CI-friendly:\n\n```bash\nnpx skills add vtex/skills\n```\n\nUse `--list` to preview available skills before installing, `--all --yes` to install everything non-interactively, or `--agent ` to target a specific tool.\n\n### Platform-specific installs (fallback)\n\n
\nInstall directly via curl, manual copy, or file upload — no CLI needed\n\n#### AGENTS.md (works with Cursor, Copilot, Codex, Windsurf, Amp, Devin, and more)\n\n```bash\ncurl -sL https://github.com/vtex/skills/releases/latest/download/agents-md.tar.gz | tar xz -C your-project/\n```\n\nThis places a root `AGENTS.md` with links to per-track files in subdirectories. Most AI coding tools discover and follow these instructions automatically.\n\n#### Cursor\n\n```bash\nmkdir -p your-project/.cursor/rules\ncurl -sL https://github.com/vtex/skills/releases/latest/download/cursor-rules.tar.gz | tar xz -C your-project/.cursor/rules/\n```\n\nEach `.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.\n\n#### GitHub Copilot\n\n```bash\nmkdir -p your-project/.github\ncurl -sL https://github.com/vtex/skills/releases/latest/download/copilot-instructions.tar.gz | tar xz -C your-project/.github/\n```\n\nPer-track files are available in `exports/copilot/` if you only need a subset.\n\n#### Claude Projects\n\nUpload files from [`exports/claude/`](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.\n\n#### OpenCode\n\n```bash\ncurl -sL https://github.com/vtex/skills/releases/latest/download/opencode-skills.tar.gz | tar xz -C ~/.config/opencode/skills/\n```\n\nEach skill becomes a directory with a `SKILL.md` file. OpenCode discovers them automatically and makes them available as loadable skills in your sessions.\n\n#### Clone and copy locally\n\n```bash\ngit clone https://github.com/vtex/skills.git\ncd skills\n\n# AGENTS.md\ncp -r exports/agents-md/. /path/to/your-project/\n\n# Cursor\nmkdir -p /path/to/your-project/.cursor/rules\ncp exports/cursor/*.mdc /path/to/your-project/.cursor/rules/\n\n# Copilot\ncp exports/copilot/copilot-instructions.md /path/to/your-project/.github/copilot-instructions.md\n\n# OpenCode\ncp -r exports/opencode/. ~/.config/opencode/skills/\n```\n\n
\n\n---\n\n## Why Use This?\n\n- **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.\n- **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.\n- **One source, six platforms.** Skills are authored once in a canonical Markdown format and exported automatically. No manual sync, no drift between tools.\n- **Built from official VTEX documentation.** Not generic LLM knowledge. Every constraint has a source, a detection pattern, and paired correct/wrong code examples.\n\n---\n\n## Supported Platforms\n\n| Platform | Format | Auto-detection | Layout |\n|---|---|---|---|\n| **AGENTS.md** | Markdown | ✅ Native in 7+ tools | 1 root file + 1 per track |\n| **Cursor** | `.mdc` rules | ✅ Glob + description | 1 per skill + per-track composites |\n| **GitHub Copilot** | Instructions | ✅ Auto-loaded | 1 master file + 1 per track |\n| **Claude Projects** | Knowledge files | Manual upload | 1 per skill + per-track composites |\n| **OpenCode** | `SKILL.md` | ✅ Auto-discovered | 1 directory per skill |\n| **Kiro** | `POWER.md` + steering | ✅ Auto-discovered | 1 `POWER.md` + per-skill steering files |\n\n---\n\n## Tracks & Skills\n\n
\nTrack 1: Well-Architected Commerce & Solution Architecture — 1 skill for cross-cutting architecture\n\nCross-cutting guidance for designing and reviewing VTEX commerce solutions. Encodes the Well-Architected Commerce pillars: Technical Foundation, Future-proof, and Operational Excellence.\n\n| Skill | Description |\n|---|---|\n| `architecture-well-architected-commerce` | Solution design, architecture reviews, and RFP-level technical structure |\n\n
\n\n
\nTrack 2: FastStore Implementation — 1 skill for storefront development\n\nCoding rules and workflow for developing VTEX FastStore storefronts. Covers TypeScript/React conventions, section overrides, BFF extensions, SCSS styling, and CMS sync workflows.\n\n| Skill | Description |\n|---|---|\n| `faststore-storefront` | Core coding rules, conventions, and development workflow for FastStore storefronts |\n\n
\n\n
\nTrack 3: Payment Connector Development — 5 skills for PPP integration\n\nAll 9 Payment Provider Protocol endpoints, Payment Provider Framework lifecycle, idempotency patterns, async payment flows, and PCI compliance via the Secure Proxy.\n\n| Skill | Description |\n|---|---|\n| `payment-provider-protocol` | All 9 PPP endpoints: 6 payment flow + 3 configuration flow |\n| `payment-provider-framework` | PPF lifecycle, configuration endpoints, retry and notification patterns |\n| `payment-idempotency` | `paymentId` and `requestId` idempotency, duplicate prevention |\n| `payment-async-flow` | Async approval, callback URLs, and the 7-day retry window |\n| `payment-pci-security` | Secure Proxy, card tokenization, and PCI constraint enforcement |\n\n
\n\n
\nTrack 4: Custom VTEX IO Apps — 24 skills for IO app development\n\nComprehensive coverage of VTEX IO app development organized into five groups: Foundations, API Exposure, Frontend, Data & Config, and Security & Operations.\n\n| Group | Skills |\n|---|---|\n| **Foundations** | `vtex-io-app-contract`, `vtex-io-service-runtime`, `vtex-io-client-integration`, `vtex-io-service-apps`¹ |\n| **API Exposure** | `vtex-io-graphql-api`, `vtex-io-http-routes`, `vtex-io-events-and-workers` |\n| **Frontend** | `vtex-io-storefront-react`, `vtex-io-admin-react`, `vtex-io-render-runtime-and-blocks`, `vtex-io-messages-and-i18n`, `vtex-io-react-apps`¹ |\n| **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` |\n| **Security & Ops** | `vtex-io-auth-tokens-and-context`, `vtex-io-auth-and-policies`, `vtex-io-security-boundaries`, `vtex-io-observability-and-ops` |\n\n¹ Original broader skills retained alongside the newer focused splits.\n\nSee [tracks/vtex-io/index.md](tracks/vtex-io/index.md) for the full skill table and learning order.\n\n
\n\n
\nTrack 5: Marketplace Integration — 4 skills for marketplace connectors\n\nSKU 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.\n\n| Skill | Description |\n|---|---|\n| `marketplace-catalog-sync` | Change Notification entry point, SKU suggestion lifecycle |\n| `marketplace-order-hook` | Feed v3 (pull) vs Hook (push), filter types, commit patterns |\n| `marketplace-fulfillment` | External Seller protocol, simulation, orders, invoice and tracking |\n| `marketplace-rate-limiting` | 429 handling, exponential backoff, circuit breaker patterns |\n\n
\n\n
\nTrack 6: Headless Front-End Development — 4 skills for headless storefronts\n\nBFF 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.\n\n| Skill | Description |\n|---|---|\n| `headless-bff-architecture` | BFF layer design, auth proxy, and API key protection |\n| `headless-intelligent-search` | Search, facets, autocomplete, and Search Events API |\n| `headless-checkout-proxy` | Checkout API proxying, session cookies, and the 5-minute order window |\n| `headless-caching-strategy` | TTL rules, stale-while-revalidate, and what must never be cached |\n\n
\n\n
\nTrack 7: Sales App Extension Development — 1 skill for Sales App extensions\n\nComplete 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.\n\n| Skill | Description |\n|---|---|\n| `sales-app-extensibility` | Full lifecycle of Sales App extension development — prerequisites, discovery, code generation, validation, and deployment |\n\n
\n\n---\n\n## Open Plugins / Cursor Directory\n\nThis repository is an [Open Plugin](https://open-plugins.com) — a portable, platform-agnostic skill pack that any AI coding tool can discover and install.\n\n```\nrules/*.mdc # Cursor rules (auto-discovered)\nskills/*/SKILL.md # Agent skills (auto-discovered)\n.cursor-plugin/plugin.json # Cursor plugin manifest\n.plugin/plugin.json # Vendor-neutral plugin manifest\n```\n\nCompatible 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.\n\n---\n\n## For Contributors\n\n
\nDirectory structure, export commands, and validation\n\n### Directory Structure\n\n```text\nvtex_skills/\n _templates/\n skill-template.md # Canonical template for new skills\n tracks/ # SOURCE — edit skill files here\n architecture/\n index.md\n skills/\n architecture-well-architected-commerce/skill.md\n faststore/\n index.md\n skills/\n faststore-storefront/skill.md\n headless/\n index.md\n skills/\n headless-bff-architecture/skill.md\n headless-intelligent-search/skill.md\n headless-checkout-proxy/skill.md\n headless-caching-strategy/skill.md\n marketplace/\n index.md\n skills/\n marketplace-catalog-sync/skill.md\n marketplace-order-hook/skill.md\n marketplace-fulfillment/skill.md\n marketplace-rate-limiting/skill.md\n payment/\n index.md\n skills/\n payment-provider-protocol/skill.md\n ...\n sales-app/\n index.md\n skills/\n sales-app-extensibility/skill.md\n vtex-io/\n index.md\n skills/\n vtex-io-app-contract/skill.md\n vtex-io-service-runtime/skill.md\n vtex-io-client-integration/skill.md\n ... (24 skills — see tracks/vtex-io/index.md)\n exports/ # auto-generated — do not edit\n agents-md/ # AGENTS.md format\n claude/ # Claude Projects format\n copilot/ # GitHub Copilot format\n cursor/ # Cursor .mdc format\n kiro/ # Kiro Power + steering format\n opencode/ # OpenCode SKILL.md format\n skills/ # auto-generated — do not edit (OpenCode export)\n rules/ # auto-generated — do not edit (Cursor export)\n scripts/\n export.ts # Generates all platform exports\n validate.ts # Validates all skill files\n package.json\n tsconfig.json\n```\n\n### Export Commands\n\nGenerate platform exports from the source skill files:\n\n```bash\n# Export to all platforms\nbun run export\n\n# Export to a specific platform\nbun run export:cursor\nbun run export:copilot\nbun run export:claude\nbun run export:agents-md\nbun run export:opencode\nbun run export:kiro\n```\n\nExports are written to `exports/{platform}/` and overwrite existing files. Run export after any skill changes before committing.\n\n### Validation\n\nCheck all skill files for quality and correctness before exporting:\n\n```bash\nbun run validate\n```\n\nThe validator runs 13 checks on every skill file, split into **hard** (must pass — block CI) and **soft** (produce warnings only):\n\n**Hard checks** (9):\n- **yaml-validity** — frontmatter parses without errors, has required fields (name, description, track, tags)\n- **description-quality** — description is at least 20 words\n- **code-block-annotations** — all opening code fences have a language annotation\n- **no-placeholders** — no `TBD`, `TODO`, or `FIXME` text in prose\n- **size-bounds** — skill files are within acceptable size limits\n- **track-consistency** — the `track` frontmatter field matches the directory\n- **globs-format** — if present, the `globs` field is a valid array of glob pattern strings\n- **filename-casing** — the file is named `skill.md` (lowercase)\n- **companion-links** — all relative links in the skill file resolve to existing files\n\n**Soft checks** (4) — produce warnings but do not block CI:\n- **required-sections** — recommended H2 sections present (decision-oriented template)\n- **detection-patterns** — constraints include a Detection field\n- **paired-examples** — constraints have both a Correct and Wrong example\n- **url-format** — VTEX doc links use the correct domain format\n\n
\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for a complete guide on adding skills, tracks, and export platforms.\n\n---\n\n## License\n\nSee [LICENSE](LICENSE) for details.\n", "bytes": 15658, "sha": "21d92eabd111f9390196fdaea8dbee1ddb7ba21c5d8bd5082c26b9c736720c74", "repo_slug": "vtex/skills", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_vtex_skills_vtex_io_react_apps_52f9d780/readme" }