headless-bff-architecture — Claude Code skill
Design a VTEX BFF for headless storefronts and keep private APIs, credentials, and shopper tokens out of browser code.
npx skills add vtex/skills --skill headless-bff-architecture -a claude-codeWhat headless-bff-architecture does
This skill guides BFF design for headless VTEX storefronts. It helps classify API routes, decide which requests need a server proxy, and keep private calls away from frontend bundles. Intelligent Search is treated as the sole VTEX API that may be called directly by the frontend; public Checkout routes still pass through the BFF because they handle sensitive data.
Shopper authentication uses VtexIdclientAutCookie inside a server-side session, never in localStorage, sessionStorage, or browser JavaScript. Machine-to-machine requests use X-VTEX-API-AppKey and X-VTEX-API-AppToken, with separate least-privilege keys for BFF modules. /pvt/ routes must be proxied, and exposing private credentials in client code violates the skill’s security rules.
What it helps with
- design a BFF for a headless VTEX storefront
- classify VTEX routes by access level
- move private API calls out of browser code
- store
VtexIdclientAutCookiein a server session - split API keys across BFF modules
Example prompts for the agent
- Design a BFF for this headless VTEX storefront and classify every API route.
- Audit the project for browser calls to
/pvt/endpoints and client-side use ofVtexIdclientAutCookie. - Suggest a server session flow and least-privilege API keys for separate BFF modules.
How to install headless-bff-architecture
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-bff-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/headless-bff-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/headless-bff-architecture/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-bff-architecture -a codex2Manually: put the files in place
.agents/skills/headless-bff-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-bff-architecture -a cursor2Manually: put the files in place
.cursor/skills/headless-bff-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills headless-bff-architecture2Manually: put the files in place
.github/skills/headless-bff-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-bff-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/headless-bff-architectureManually: put the files in place
.devin/skills/headless-bff-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-bff-architecture -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 headless-bff-architecture
How do I install headless-bff-architecture in Claude Code?
Run npx skills add vtex/skills --skill headless-bff-architecture -a claude-code, then check ~/.claude/skills/headless-bff-architecture/SKILL.md.
What does headless-bff-architecture do?
The skill provides rules for building a VTEX BFF, routing private requests through it, classifying APIs, and protecting credentials and shopper sessions.
Which VTEX API can the frontend call directly?
Only Intelligent Search is marked safe for direct frontend calls. Private /pvt/ routes and public Checkout endpoints must use the BFF.
