decocms

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, debugging its output, extending it with new transforms, or understanding what it does. Located at packages/blocks-cli/scripts/migrate.ts in @decocms/blocks-cli.

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, matchers, and islands elimination. Single entry point — all deep-dive content in references/.

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 package.json pins @decocms/start to 6.x and/or @decocms/apps to 5.x. Not for Fresh/Deno sites (use the Fresh→TanStack migrator) and not for Next.js sites (use deco-next-package-migration).

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 selection, staleTime/gcTime configuration, cache headers, and head/SEO setup. Use when creating a new Deco site, migrating routes from Fresh, or debugging route-level caching issues.

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 site.

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 prerelease, or imports from @decocms/start/next, @decocms/start/core, or @decocms/start/node.

Run the Fresh/Deno → TanStack Start migrator from this repo against a target site workspace. Resets the target to its Fresh/Deno state (origin/main), then runs the local migration script. Use for testing the migrator on real sites. For sites ALREADY on TanStack that just need the @decocms/start@6.x → split-7.x package upgrade, use the decocms-v6-to-v7-upgrade skill instead.

Port the VTEX commerce app from deco-cx/apps (Fresh/Deno) to @decocms/apps-start (TanStack Start/Node). The goal is to mirror the original production code that runs on thousands of stores, adapting only what is necessary for TanStack/Node. Covers full structural mapping (141 files → apps-start equivalent), adaptation patterns (Deno→Node, signals→react-query, manifest→exports, ctx.bag→configureVtex), schema.org compliance, and a file-by-file gap analysis. Use when porting VTEX code, fixing bugs in apps-start, or ensuring parity with the original.

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, personalize a page per audience/segment, show different banners per device or location, schedule a promotion by date/cron, add a new variant-able type (promotion, VTEX segment, product list, menu items), write a custom matcher, or generally wire up `website/flags/multivariate*` in `.deco/blocks/*.json`. Covers the JSON shape (`variants: [{ value, rule }]`), the resolution order (first match wins, catch-all last), every built-in matcher (`always`, `never`, `device`, `date`, `cron`, `random`, `cookie`, `host`, `pathname`, `queryString`, `userAgent`, `location`, `site`, `environment`, `multi`, `negate`), how to compose them with `multi` (and/or) and `negate`, the 8-line boilerplate to create your own `flags/multivariate/<type>.ts`, the shape of a custom `ma

Install and configure the Blog Manager on a deco-site storefront. Covers the blog app, page routes, sections, Blog Manager MCP connection in Studio, and first-run brand context initialization.

Use when inside a deco.cx ecommerce repository (deco.ts present, decobot in PR history) and the user wants automated QA for purchase-journey correctness — set up E2E coverage, test the add-to-cart / checkout flow, or scaffold a CI gate for the store with the @decocms/qa engine. NOT for load/cache performance testing (use deco-e2e-testing) or hand-written Playwright spec files.

Quick fixes for common, isolated issues in deco.cx storefronts. Use when the user reports a specific symptom that doesn't warrant a full skill. This is a growing knowledge base — add new entries as they're discovered.

Make deco storefront pages with matchers (A/B tests, date windows, segment targeting) cacheable at the CDN edge. Use when a page uses matcher blocks or MultivariateFlag and returns Cache-Control: no-store. Covers the framework's cache-decision gates, the cache: 'no-store' default on site loaders, the missing cacheable=true on custom matchers, the inline-cookie script (1.201.2+), the cold-visitor bias trade-off, and a diagnostic checklist.

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.

Read and extract text from .pdf files, page by page. Use when the user uploads or references a PDF to read or summarize.

Read and inspect existing .pptx PowerPoint files (text, speaker notes, slide images). Use only for reading uploaded PowerPoint files — to AUTHOR a deck use the slides skill instead.

Read and extract cell data from .xlsx Excel spreadsheets as TSV. Use when the user uploads or references an Excel file to read or summarize.

Route a file to the right reader by extension (pptx, docx, xlsx, pdf, and plain text). Use as the entry point when asked to read or summarize an uploaded file of unknown type.

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

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 _meta.ui.resourceUri → resource → constants → vite entry → html).

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.

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 explaining release channels to a user. Covers the PR base selection decision tree, semantic-release branching model, npm dist-tags (latest, next), customer-facing install commands, and gotchas (the canonical CI-skip token; package.json lagging the git tag).