vtex-io-observability-and-ops — Claude Code skill: how to install
Adds structured logs and client metrics to VTEX IO backend services, so production failures are easy to trace before and after a release.
npx skills add vtex/skills --skill vtex-io-observability-and-ops -a claude-codeWhat vtex-io-observability-and-ops does
This skill steers an agent toward VTEX IO backend services you can actually debug in production. When a route or worker catches an error, the agent logs it through ctx.vtex.logger at error level with identifiers like orderId and account, then rethrows. Plain console.log is out, because only the platform logger feeds VTEX's searchable log collection.
Calls to external APIs get a metric option with a name tied to the integration, like partner-sync-catalog, so latency and error counts show up per operation. For APIs with strict rate limits, the skill pairs short timeouts with retries that back off, plus caching for reads that repeat.
A bare catch that just returns counts as a bug here, and so does a log line carrying an auth header or raw request body. Browser-side monitoring is outside its scope.
What it helps with
- find routes and workers that swallow errors silently
- tag partner API calls with a named
metric - strip tokens, auth headers and raw bodies from log lines
- cut burst traffic to rate-limited APIs with caching and backoff retries
- review whether an on-call engineer could diagnose a flow before release
Example prompts for the agent
- Review this VTEX IO service for production readiness: logging, metrics, error visibility
- Add a
metricto every call in the partner API client and swapconsole.logforctx.vtex.logger - Errors in the catalog sync worker vanish. Make sure failures show up in the logs
How to install vtex-io-observability-and-ops
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-observability-and-ops -a claude-code2Manually: put the files in place
~/.claude/skills/vtex-io-observability-and-ops/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vtex-io-observability-and-ops/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-observability-and-ops -a codex2Manually: put the files in place
.agents/skills/vtex-io-observability-and-ops/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-observability-and-ops -a cursor2Manually: put the files in place
.cursor/skills/vtex-io-observability-and-ops/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills vtex-io-observability-and-ops2Manually: put the files in place
.github/skills/vtex-io-observability-and-ops/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-observability-and-ops -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-observability-and-opsManually: put the files in place
.devin/skills/vtex-io-observability-and-ops/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-observability-and-ops -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-observability-and-ops
How do I install vtex-io-observability-and-ops in Claude Code?
Run npx skills add vtex/skills --skill vtex-io-observability-and-ops -a claude-code. The skill file ends up at ~/.claude/skills/vtex-io-observability-and-ops/SKILL.md.
What does vtex-io-observability-and-ops do?
It makes VTEX IO services easier to operate: structured logs through ctx.vtex.logger, metric names on important client calls, and no silently swallowed errors. For rate-limited APIs it also recommends caching, short timeouts and backoff retries.
Can this skill monitor a storefront frontend?
No. It targets VTEX IO backend services. Frontend analytics, browser monitoring, app policy declaration and trust-boundary modeling are handled elsewhere.
