vtex-io-session-apps — Claude Code skill: what it does, how to install
vtex-io-session-apps — a skill for building and debugging VTEX IO session transform apps that compute state for storefront, pricing, and checkout from session inputs.
no license 1,200 installs ★ 47 updated 2026-10-14
npx skills add vtex/skills --skill vtex-io-session-apps -a claude-codeWhat vtex-io-session-apps does
The skill applies when integrating with the VTEX session system (vtex.session): explains how an app declares input and output fields in configuration.json, how VTEX builds a dependency graph (DAG) between transforms, and when one transform reruns because another changed. Covers the split between public.* (input surface for shopper intent) and private namespaces (profile, storefront-permissions, checkout) as the read model for frontend.
The skill forbids duplicating another app's output fields: if storefront-permissions owns costcenter, your transform must read that field as input, not write its own copy. Without account and workspace in LRU cache keys, a transform will return data from the wrong workspace. To propagate values into native transforms, update their input fields (public.postalCode) instead of overwriting checkout.postalCode directly.
The skill targets VTEX IO and B2B scenarios where storefront-permissions, custom transforms, and checkout interact through session.
What it helps with
- declare input and output fields of a session transform in
configuration.json - read
storefront-permissions.costcenterand computemyapp.priceTable - update
public.postalCodeto rerun thecheckouttransform - cache an external backend request via VBase stale-while-revalidate
- request specific session fields on the frontend via
items=rona.storeNumber
Example prompts for the agent
- Write a VTEX IO session transform that reads
storefront-permissions.organizationand outputsmyapp.storeNumber - Explain why my transform runs twice when
public.countrychanges - Show
configuration.jsonfor a transform that depends onprofileandstorefront-permissions
How to install vtex-io-session-apps
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-session-apps -a claude-code2Manually: put the files in place
~/.claude/skills/vtex-io-session-apps/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vtex-io-session-apps/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-session-apps -a codex2Manually: put the files in place
.agents/skills/vtex-io-session-apps/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-session-apps -a cursor2Manually: put the files in place
.cursor/skills/vtex-io-session-apps/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills skills/vtex-io-session-apps2Manually: put the files in place
.github/skills/vtex-io-session-apps/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-session-apps -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-session-appsManually: put the files in place
.devin/skills/vtex-io-session-apps/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-session-apps -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 vtex-io-session-apps
How to install vtex-io-session-apps in Claude Code?
Run npx skills add vtex/skills --skill vtex-io-session-apps -a claude-code, then open ~/.claude/skills/vtex-io-session-apps/SKILL.md.
What does vtex-io-session-apps do?
The skill helps build VTEX IO session transform apps: explains the dependency graph (DAG), input/output split, namespace ownership, and caching rules inside transforms.
Why can't I duplicate another app's fields in my namespace?
Copying fields like costcenter from storefront-permissions into your namespace creates two sources of truth. On partial session updates, consumers read inconsistent values and race conditions appear.