headless-caching-strategy — Claude Code skill: setup and caching
Sets caching rules and TTL values for headless VTEX storefronts. Keeps public endpoints fast while preventing accidental caching of sensitive shopper data.
npx skills add vtex/skills --skill headless-caching-strategy -a claude-codeWhat headless-caching-strategy does
This skill governs caching across headless VTEX stores. It isolates public catalog traffic from transactional shopper requests. Without caching, API rate limits trigger 429 errors. Keeping search responses and category trees at the edge or within a BFF cache drops latency by 200–500ms.
The logic relies on stale-while-revalidate alongside moderate TTLs between 2 and 15 minutes. It sets explicit windows: category trees persist up to 15 minutes, while search autocomplete entries refresh after one or two minutes. Invalidation should follow catalog update events rather than multi-hour expiration windows.
Sensitive shopper routes must stay uncached. Storing checkout or customer details creates compliance liabilities and corrupts carts. Because of this, the skill forbids caching Checkout, Profile, OMS, and Payments on any tier, including Redis and browser storage.
What it helps with
- prevent VTEX API rate limit errors caused by repetitive search queries
- implement stale-while-revalidate patterns inside an Express BFF layer
- assign suitable TTL values for public catalog endpoints
- block checkout and personal customer records from being cached
Example prompts for the agent
- Set up an in-memory stale-while-revalidate cache for my VTEX category tree in Express.
- What TTL values and headers should I configure for Intelligent Search endpoints?
- Review my storefront API proxy to ensure Checkout and Profile routes stay uncached.
How to install headless-caching-strategy
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-caching-strategy -a claude-code2Manually: put the files in place
~/.claude/skills/headless-caching-strategy/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/headless-caching-strategy/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-caching-strategy -a codex2Manually: put the files in place
.agents/skills/headless-caching-strategy/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-caching-strategy -a cursor2Manually: put the files in place
.cursor/skills/headless-caching-strategy/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills headless-caching-strategy2Manually: put the files in place
.github/skills/headless-caching-strategy/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-caching-strategy -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/headless-caching-strategyManually: put the files in place
.devin/skills/headless-caching-strategy/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-caching-strategy -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-caching-strategy
How to install headless-caching-strategy in Claude Code?
Run npx skills add vtex/skills --skill headless-caching-strategy -a claude-code. The tool places the skill definition into ~/.claude/skills/headless-caching-strategy/SKILL.md.
Which VTEX endpoints must never be cached?
Never cache Checkout (/api/checkout/), Profile (/api/profile-system/pvt/), OMS (/api/oms/pvt/orders), Payments (/api/payments/), or private pricing routes. Caching them exposes personal identity details and breaks checkout sessions.
When should you skip this skill?
Do not use it for broad BFF routing structure or query construction for Intelligent Search. VTEX provides dedicated skills like headless-bff-architecture and headless-intelligent-search for those areas.
