architecture-well-architected-commerce — Claude Code skill: guide
Reviews cross-cutting VTEX commerce architecture against three core pillars. It guides decisions between standard platform capabilities and custom extensions.
npx skills add vtex/skills --skill architecture-well-architected-commerce -a claude-codeWhat architecture-well-architected-commerce does
This skill evaluates high-level architecture decisions across VTEX e-commerce setups. It anchors review work to three pillars: technical foundation, future-proof adaptability, and operational discipline. The agent reviews solution layouts across headless frontends, payment flows, and marketplace connectors during early planning.
The guidance enforces using out-of-the-box features over custom code. Developers must justify building VTEX IO apps whenever standard platform settings exist. Extra hops across systems are discouraged because each network bridge adds failure risks and operational overhead.
This meta-skill intentionally skips low-level coding steps. Detailed implementation for CDN cache rules, Master Data schemas, or fulfillment routes gets routed to dedicated product track skills.
What it helps with
- audit cross-cutting VTEX solution architecture before launch
- decide between native platform features and custom VTEX IO apps
- structure technical architecture reviews for RFP proposals
- identify redundant integration hops across commerce modules
Example prompts for the agent
- Review our proposed VTEX headless checkout flow against the Well-Architected framework.
- Help us justify whether we need a custom VTEX IO app or native marketplace settings.
- Evaluate our integration design to minimize hops between VTEX and our ERP.
How to install architecture-well-architected-commerce
1Skills CLI (Vercel)
npx skills add vtex/skills --skill architecture-well-architected-commerce -a claude-code2Manually: put the files in place
~/.claude/skills/architecture-well-architected-commerce/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/architecture-well-architected-commerce/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill architecture-well-architected-commerce -a codex2Manually: put the files in place
.agents/skills/architecture-well-architected-commerce/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill architecture-well-architected-commerce -a cursor2Manually: put the files in place
.cursor/skills/architecture-well-architected-commerce/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills architecture-well-architected-commerce2Manually: put the files in place
.github/skills/architecture-well-architected-commerce/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill architecture-well-architected-commerce -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/architecture-well-architected-commerceManually: put the files in place
.devin/skills/architecture-well-architected-commerce/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill architecture-well-architected-commerce -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about architecture-well-architected-commerce
How to install architecture-well-architected-commerce in Claude Code?
Run npx skills add vtex/skills --skill architecture-well-architected-commerce -a claude-code in your terminal.
What criteria does this skill use to evaluate solutions?
It reviews designs against technical foundation, future adaptability, and operational quality. Every major architectural decision must map to at least one of these pillars.
Does this skill configure VTEX IO code directly?
No, it focuses strictly on overarching design decisions. Low-level work like CDN cache headers or Master Data models routes to dedicated product track skills.
