decocms

Reconcile a migrated TanStack repo against upstream changes that landed on the Fresh/Deno source repo after the migration cut. Runs `deco-reconcile` to produce one diff per changed file, then ports each one by hand — a rebase, not a re-migration. Use when a…

Consolidated migration skill for Deco storefronts. Phase-based playbook for Fresh/Preact/Deno to TanStack Start/React/Cloudflare Workers. Covers all phases from scaffold to async rendering, plus post-migration patterns, hydration fixes, navigation, search,…

Cart v2 for VTEX storefronts — modular, granular, framework-agnostic. Explains the thesis (reduce cart API traffic, lazy cart creation, projection/sections fragmentation), the available hooks and loaders, and how to wire them in a Next.js or TanStack Start…

Automated migration script that converts Deco storefronts from Fresh/Preact/Deno to TanStack Start/React/Cloudflare Workers. Runs 8 phases (analyze, scaffold, transform, cleanup, report, verify, bootstrap, compile). Use when running the migration script,…

Migrates a Next.js App Router site off the abandoned @decocms/start@5.x /next, /core, /node export tiers onto the current @decocms/blocks, @decocms/blocks-admin, and @decocms/nextjs packages. Use when a site's package.json pins @decocms/start to a 5.x-next…

Upgrades an already-TanStack site from the monolithic @decocms/start@6.x + @decocms/apps@5.x to the split 7.x packages (@decocms/blocks, @decocms/tanstack, @decocms/blocks-admin, @decocms/blocks-cli, @decocms/apps-*). Use when a TanStack Start site's…

Configure CMS-driven routes in @decocms/tanstack using cmsRouteConfig, cmsHomeRouteConfig, and admin routes. Covers the catch-all route ($.tsx), homepage route (index.tsx), admin protocol routes (meta, render, invoke), ignoreSearchParams for variant…

Implement end-to-end performance tests for any Deco e-commerce site with lazy section tracking, cache analysis, and observability. Use this skill when asked to set up e2e tests, create performance testing infrastructure, or test user journeys on a Deco/VTEX…

Create a new page on a deco.cx storefront — including route, metadata, sections, and dynamic route params (e.g. /category/:slug). Use when the user asks to add, create, or scaffold a new page or route in a deco site, or to pass a URL param into a…

Understand and configure image optimization in deco.cx storefronts — components, quality settings, bypass rules, platform-specific handling, CDN proxy, and format negotiation. Use when the user asks about images, image quality, image optimization, or image…

Understand and configure video in deco.cx storefronts — the Video component, autoplay, and especially audio/sound. Use when the user asks about video, video sound, audio, "video with no sound", "video is silent", "how to unmute", muted, autoplay, or how to…

Shrink first-byte HTML and embedded payloads: trim framework state scripts (Fresh/Next), event data attributes, JSON-LD bloat, and duplicate responsive markup so the client receives less markup and JSON.

Diagnose and fix headless login issues on VTEX storefronts — covering authorized domain setup and simulating an authenticated session by copying VtexIdclientAutCookie cookies.

Use when debugging what crawlers or bots see on a deco site, verifying if SSR is active for bots, or diagnosing firstByteThresholdMS behavior.

Use when a site's SEO metadata (title, og:tags, LD+JSON) is missing, incomplete, or handled by a weak custom component. Covers configuring the apps SEO sections for general pages, PDPs, and PLPs via the deco admin.

Configure deco.cx Variants — the mechanism that swaps the value of a section, page, image, message, or ANY custom-typed prop based on a matcher rule (device, cookie, date, A/B test, geo, path, query string, etc.). Use when the user asks to A/B test a section,…

Install and self-host deco Studio (the open-source control plane) on the user's own infrastructure. Use when the user wants to install, run, self-host, or deploy Studio locally (Docker, Rancher Desktop, kind, minikube) or on Kubernetes (managed or…

Build or style React UI with the decocms product design system (@decocms/ui). Use when creating interfaces, pages, or components in a project that should look like decocms products, when the user mentions "design system", "@decocms/ui", "decocms style", or…

Guide for adding new MCP tools with consistent patterns for schemas, tool definitions, registry updates, and Better Auth integration

Prepare code for review by running quality checks, creating conventional commits, and opening pull requests. Use when the user wants to commit changes, create a PR, prepare for code review, or asks to commit their work.

Script against the org's MCP tools from inside the sandbox — discover schemas under .deco/tools/, call one tool from the shell with `typegen call`, or batch many calls in a script. Use whenever a task needs repeated or bulk tool calls (same tool many times,…

Create and edit presentation decks as single self-contained HTML files with a live, editable preview and print-to-PDF export. Use when the user wants slides, a deck, or a presentation.

Render any text file (HTML, markdown, config, SQL, email) from a mustache template plus JSON data. Use when an output's shape is fixed ahead of time and only the values change.

Read and extract text, tables, and structure from .docx Word documents. Use when the user uploads or references a Word file to read or summarize.

Build and maintain MCPs in the decocms/mcps monorepo. Covers deco HTTP server pattern (withRuntime, createPrivateTool), tool definitions, app.json config, and the two MCP types: custom server vs official external server.

Build responsive deco CMS home widgets (MCP-App tiles). Covers the resizable tile grid (Size picker up to 4×5), observed pixel sizes, the golden rules for filling + scrolling inside a tile, ResizeObserver-based breakpoints, and how to register a widget (tool…

Understand and manage CI/CD for the decocms/mcps monorepo. Covers deploy.yml (Cloudflare Workers), publish-registry.yml (registry publish), checks.yml, and publish-jsr.yml. Explains the two deploy platforms and how detection works.

Generate a structured Markdown report with YAML frontmatter for repository health monitoring. Use when the user asks to create a report, health check, audit, scan result, or status update for a repository.

Use when the user asks to add support for a new deployment target or platform (e.g., Cloudflare Workers, Deno, Node.js, AWS Lambda), create a new entrypoint, or make the app deployable to a specific environment.

Use when the user asks to add a new MCP tool, create a tool with UI, scaffold a tool, or add functionality to the MCP App server. Also use when adding API-only tools without a UI component.

Use when the user asks to update their MCP App to the latest template version, sync with upstream template, pull in template changes, upgrade the template, or migrate to a newer version of the MCP App template.

Use when the user asks to publish to the store, publish to the registry, publish to studio, set up publishing, configure deco.json/app.json for publishing, troubleshoot publish errors, or understand how the deco store publish flow works.

Use when the user asks to add a new MCP tool, create a tool with UI, scaffold a tool, or add functionality to the MCP App server. Also use when adding API-only tools without a UI component.

Use when the user asks to update their MCP App to the latest template version, sync with upstream template, pull in template changes, upgrade the template, or migrate to a newer version of the MCP App template.

Choose the correct base branch (main vs next) when opening a PR against @decocms/apps, and operate the stable / prerelease release pipeline. Use BEFORE running `gh pr create` or pushing a branch, and when promoting a prerelease, publishing a hotfix, or…