create-content-sdk-app 2.0.0 → 2.0.1

package/dist/templates/nextjs/.agents/skills/content-sdk-component-data-strategy/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-component-data-strategy
+description: Component data for Pages Router: after getPage use client.getComponentData(page.layout, context, components) to resolve component props; pass result to layout renderer. All Sitecore-driven component data goes through this flow. Use when wiring component data or BYOC.
+---
+
+# Content SDK Component Data Strategy (Pages Router)
+
+This app **uses getComponentData**. After getPage, use **client.getComponentData(page.layout, context, components)** to resolve component props and pass the result to the layout renderer. All Sitecore-driven component data goes through this flow.
+
+## When to Use
+
+- User asks how to pass data to components, wire component props, or integrate custom/BYOC components.
+- Task involves getComponentData, component props, or BYOC.
+- User mentions "component data," "props," "BYOC," or "getComponentData."
+
+## How to perform
+
+- In [[...path]].tsx: getPage(path, { locale: context.locale }), then getDictionary, then getComponentData(page.layout, context, components). Return props to Layout; do not fetch in _app or in child components. Register BYOC in .sitecore/component-map.ts; getComponentData passes resolved props.
+
+## Hard Rules
+
+- **Flow in catch-all page:** In getStaticProps/getServerSideProps: (1) `client.getPage(path, { locale: context.locale })`, (2) `client.getDictionary({ site: page.siteName, locale: page.locale })`, (3) `client.getComponentData(page.layout, context, components)` to resolve component props. Return `{ props: { page, dictionary, componentProps }, notFound: !page }`. Pass these props to Providers and Layout; do not fetch Sitecore data in _app.
+- Do not fetch per-component data in parallel outside this flow unless the app pattern explicitly does so. All Sitecore-driven component data goes through getComponentData.
+- Single client instance; do not create a new client inside components. The client is used in getStaticProps/getServerSideProps and in API routes.
+- **BYOC or custom components:** Must be registered in `.sitecore/component-map.ts` and receive props in the shape the layout expects (e.g. fields, params). getComponentData will pass the resolved props.
+- Do not fetch layout or page data inside a child component (e.g. another getPage call); fetch at the catch-all page level and pass props via getComponentData and layout.
+
+## Stop Conditions
+
+- Stop if the user wants to fetch page/layout data inside a child component; recommend fetching in [[...path]].tsx and passing via getComponentData and layout.
+- Do not duplicate getComponentData or getPage logic across components; keep data fetching in the catch-all page only.
+- Do not fetch Sitecore data in _app; all data flows from [[...path]].tsx.
+
+## References
+
+- content-sdk-graphql-data-fetching and [AGENTS.md](../../../AGENTS.md) for getPage, getComponentData, and data flow.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-component-registration/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-component-registration
+description: Registers Sitecore components in .sitecore/component-map.ts so layout and editing can resolve them. Pages Router uses a single map; used by getComponentData and editing API routes. Use when registering a new component or when layout/editor cannot find a component.
+---
+
+# Content SDK Component Registration (Pages Router)
+
+Register components in the Sitecore component map so the layout and editing pipeline can resolve and render them. This app has a **single** map: `.sitecore/component-map.ts`.
+
+## When to Use
+
+- After scaffolding or adding a new Sitecore component (must be registered).
+- User reports a component not rendering, "component not found," or layout/placeholder showing raw component name.
+- Task involves `.sitecore/component-map.ts`.
+- User asks how to register a component or fix component resolution.
+
+## How to perform
+
+- Open `.sitecore/component-map.ts` and add an entry mapping the layout component name to the React component import. The map is used by getComponentData and editing API routes; keep keys consistent with layout and existing entries.
+
+## Hard Rules
+
+- Every component rendered from Sitecore layout must be registered in `.sitecore/component-map.ts`. Keep the map in sync with `src/components/`.
+- The map is used by `getComponentData(page.layout, context, components)` in the catch-all page and by editing API routes (`src/pages/api/editing/config.ts`, `render.ts`, `feaas/render.ts`).
+- Use consistent component names (same key in map as used in layout). Follow existing naming in the map.
+- Do not remove or rename registrations without updating all references (layout, getComponentData, editing routes).
+
+## Stop Conditions
+
+- Stop if modifying the component map would break existing layout or editing; suggest a safe change or ask for confirmation.
+- Do not edit `.sitecore/metadata.json` or import-map unless the task explicitly requires it.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for component map and editing routes.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-component-scaffold/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: content-sdk-component-scaffold
+description: Creates new Sitecore components with correct file structure, props interface, and placement under src/components/. Use when adding a new component from scratch or scaffolding a component. Pages Router: register in .sitecore/component-map.ts only.
+---
+
+# Content SDK Component Scaffold (Pages Router)
+
+Scaffold new Sitecore components so they integrate with the layout and editing pipeline. This app uses Pages Router with a single component map.
+
+## When to Use
+
+- User asks to add a new Sitecore component, create a component from scratch, or scaffold a component.
+- Task involves creating a new React component that will be rendered from Sitecore layout/placeholders.
+- User mentions "new component," "add component," or "component file structure."
+
+## How to perform
+
+- Create a new file under `src/components/` (or existing feature folder). Define props (fields, params), export a single default component. Register in `.sitecore/component-map.ts` (content-sdk-component-registration). Run `npm run build` to verify.
+
+## Hard Rules
+
+- Place components under `src/components/`. Use existing folder conventions.
+- Define a props interface with the component's fields (e.g. `fields: { title: Field; ... }`) and any params. Use types from `@sitecore-content-sdk/react` or the app's types.
+- Export a single default component; one component per file unless the app pattern differs.
+- After creating the component file, register it in `.sitecore/component-map.ts` (see content-sdk-component-registration). Do not leave the component unregistered. Pages Router has a single map used by getComponentData and editing API routes.
+
+## Stop Conditions
+
+- Do not create components in `.next/`, `node_modules/`, or build output.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for app structure and component map.
+- [Skills.md](../../../Skills.md) for capability map. [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-component-variants/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-component-variants
+description: Implements component variants: different renderings or data-driven variants of the same component type. Pages Router: register in .sitecore/component-map.ts; getComponentData resolves props. Use when one component has multiple presentations.
+---
+
+# Content SDK Component Variants (Pages Router)
+
+One component definition can have multiple presentations or data-driven variants. Component props are resolved by **getComponentData(page.layout, context, components)**; keep registration and layout aligned.
+
+## When to Use
+
+- User asks for different "variants," "versions," or "presentations" of a component.
+- Task involves rendering the same component type with different layouts or props based on data (e.g. variant field or style).
+- User mentions "component variants," "variations," or "multiple renderings."
+
+## How to perform
+
+- Prefer one component that accepts variant/style via props and branches internally; or multiple map entries if the app uses one key per variant. Use layout/fields/params for variant; register in `.sitecore/component-map.ts`. getComponentData resolves props; align with existing app convention.
+
+## Hard Rules
+
+- Prefer a single component registration that accepts variant/style data (e.g. params or fields) and branches internally, over multiple map entries for the same logical component unless the app pattern uses separate registrations per variant.
+- Use props (fields, params) from layout to decide variant; do not rely on global state or URL for variant selection when data comes from Sitecore. getComponentData passes the layout-driven props to the component.
+- Register in `.sitecore/component-map.ts` only. If the app uses one key per variant, register each; if one key with variant param, single registration. Follow existing app convention.
+- Keep the component map in sync with src/components/.
+
+## Stop Conditions
+
+- Stop if the variant model (one registration vs many) is unclear; ask or follow the app's existing pattern.
+- Do not add new component map entries without ensuring layout and editing can provide the corresponding data.
+- Do not assume variant field names (e.g. "variant," "style") without checking the layout definition.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) and content-sdk-component-registration for the map.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-dictionary-and-i18n/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: content-sdk-dictionary-and-i18n
+description: Dictionary and i18n for Pages Router: Next.js i18n in next.config.js (i18n.locales, defaultLocale). Per-request locale is context.locale in getStaticProps/getServerSideProps. Fetch dictionary with client.getDictionary({ site: page.siteName, locale: page.locale }) after getPage. Use when adding or changing translated content or locale behavior.
+---
+
+# Content SDK Dictionary and i18n (Pages Router)
+
+This app uses **Next.js built-in i18n**. There is no [locale] in the URL path; locale is provided by Next.js as `context.locale` in getStaticProps/getServerSideProps.
+
+## When to Use
+
+- User asks to add or change translated content, locale, or dictionary.
+- Task involves getDictionary, Next.js i18n, or context.locale.
+- User mentions "dictionary," "i18n," "locale," or "translation."
+
+## How to perform
+
+- Locales: `next.config.js` → i18n.locales, defaultLocale. In getStaticProps/getServerSideProps use context.locale; after getPage use client.getDictionary({ site: page.siteName, locale: page.locale }). Use a single getDictionary per request. Do not assume locale from headers.
+
+## Hard Rules
+
+- **Config:** `next.config.js` → `i18n.locales` and `i18n.defaultLocale`. Match (or subset) Sitecore languages.
+- **Per-request locale:** Use `context.locale` in getStaticProps and getServerSideProps. Pass it to `client.getPage(path, { locale: context.locale })`. After fetching the page, use `page.siteName` and `page.locale` (or `context.locale`) for `client.getDictionary({ site: page.siteName, locale: page.locale })` and for getComponentData.
+- Align locales in next.config.js with Sitecore languages (e.g. from sitecore.config.ts defaultLanguage). Use a single client.getDictionary per request for the active site/locale.
+- **Do not** assume locale from headers or a different source; always use `context.locale` and the page's site/locale for Sitecore calls.
+
+## Stop Conditions
+
+- Stop if adding a new locale without confirming it exists in Sitecore and in next.config.js i18n.
+- Do not duplicate dictionary fetching without a clear need; prefer one fetch per request in the catch-all page.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for Next.js i18n and getDictionary usage.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-editing-safe-rendering/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-editing-safe-rendering
+description: Ensures components render safely in XM Cloud editing and preview. Pages Router uses context.preview and context.previewData; use client.getPreview(context.previewData) or getDesignLibraryData(context.previewData) when in preview. Use when making components work in the Sitecore editor or fixing preview/editing behavior.
+---
+
+# Content SDK Editing-Safe Rendering (Pages Router)
+
+Ensure components behave correctly in XM Cloud editing, preview, and design library. This app uses **context.preview** and **context.previewData** in getStaticProps/getServerSideProps for editing data.
+
+## When to Use
+
+- User asks about editing, preview, design library, or "component not working in editor."
+- Task involves draft mode, editing chromes, or design library integration.
+- Fixing issues where components render differently or break in editor vs published.
+- User mentions getPreview, getDesignLibraryData, or editing API routes.
+
+## How to perform
+
+- In [[...path]].tsx getStaticProps/getServerSideProps: check context.preview; when true use isDesignLibraryPreviewData(context.previewData) to choose getDesignLibraryData vs getPreview; otherwise getPage + getDictionary + getComponentData. Editing routes: config uses EditingConfigMiddleware, render uses EditingRenderMiddleware, feaas/render uses FEAASRenderMiddleware; export handler as default.
+
+## Hard Rules
+
+- In the catch-all page (`src/pages/[[...path]].tsx`), use `context.preview` and `context.previewData`. When in preview, use `isDesignLibraryPreviewData(context.previewData)` to distinguish: if true, use `client.getDesignLibraryData(context.previewData)`; otherwise use `client.getPreview(context.previewData)`. When not in preview, use `getPage(path, { locale: context.locale })` then getDictionary and getComponentData as usual.
+- Do not assume editing/preview context in components that might run in static or non-editing contexts; guard on context.preview in getStaticProps/getServerSideProps.
+- Editing API routes: `src/pages/api/editing/config.ts` uses `EditingConfigMiddleware({ components, metadata }).getHandler()` (import components from `.sitecore/component-map`, metadata from `.sitecore/metadata.json`). `src/pages/api/editing/render.ts` uses `EditingRenderMiddleware().getHandler()`. `src/pages/api/editing/feaas/render.ts` uses `FEAASRenderMiddleware().getHandler()`. Export the handler as default. Do not duplicate client creation; config uses the same component map as the app.
+- Never commit editing secrets; use environment variables and document in .env.example only.
+
+## Stop Conditions
+
+- Stop and clarify if the issue is preview vs design library vs published; behavior differs.
+- Do not change proxy or middleware order to "fix" editing; editing is driven by API routes and context.previewData.
+- Do not recommend disabling secret validation without explicit user request and warning.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for data fetching, preview flow, and editing routes.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-field-usage-image-link-text/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-field-usage-image-link-text
+description: Renders Sitecore fields using SDK field components (Text, RichText, Image, Link) with proper validation and fallbacks. Use when rendering content fields or when the user mentions Text, RichText, Image, Link, or field components.
+---
+
+# Content SDK Field Usage (Pages Router)
+
+Use SDK field components to render Sitecore fields with proper validation and fallbacks.
+
+## When to Use
+
+- User asks how to render a title, body, image, or link from Sitecore.
+- Task involves displaying content fields, fixing empty/broken images or links, or using RichText/Text/Image/Link components.
+- User mentions "field," "Image," "Link," "Text," "RichText," or "field value."
+
+## How to perform
+
+- Use SDK field components: `<Text field={fields?.title} />`, `<RichText field={fields?.content} />`, `<Image field={fields?.image} />`, `<Link field={fields?.link} />`. Guard with `fields?.` when optional; use tag prop on Text when needed. Do not hardcode media or link URLs from Sitecore.
+
+## Hard Rules
+
+- Prefer SDK field components over manual field value extraction: `<Text field={fields?.title} />`, `<RichText field={fields?.content} />`, `<Image field={fields?.image} />`, `<Link field={fields?.link} />`. Use tag prop for Text when needed (e.g. tag="h1").
+- Validate or guard field existence before rendering when fields can be optional (e.g. `fields?.title`). Handle null/undefined and empty fields gracefully.
+- Do not hardcode image or link URLs when the data comes from Sitecore; use the field components or helpers that resolve media/URLs.
+- Follow the app's import pattern (e.g. from lib or components).
+
+## Stop Conditions
+
+- Stop if the field structure (name or type) is unknown; suggest checking the layout/data shape or asking the user.
+- Do not assume field names (e.g. "title") without confirmation when the template might use different names.
+- Do not commit or log raw field values that might contain PII or secrets.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for component and Sitecore patterns.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-graphql-data-fetching/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: content-sdk-graphql-data-fetching
+description: Fetches page, dictionary, and component data via the single Sitecore client. Pages Router: getPage(path, { locale: context.locale }), getDictionary({ site: page.siteName, locale: page.locale }), getComponentData(page.layout, context, components); for SSG use getPagePaths(sites, context?.locales). Use when fetching page or dictionary content.
+---
+
+# Content SDK GraphQL Data Fetching (Pages Router)
+
+All Sitecore data fetching goes through the single client in `src/lib/sitecore-client.ts`. Use getPage, getDictionary, and **getComponentData** in the catch-all page. Path from **extractPath(context)**; locale from **context.locale**.
+
+## When to Use
+
+- User asks how to fetch page data, layout, or dictionary phrases.
+- Task involves getPage, getDictionary, getComponentData, getPreview, getDesignLibraryData, or getPagePaths.
+- User mentions "sitecore client," "Layout Service," "page data," or "dictionary."
+
+## How to perform
+
+- Use the client from `src/lib/sitecore-client.ts` only. In [[...path]].tsx: use `extractPath(context)` and `context.locale`; call getPage(path, { locale: context.locale }), then getDictionary and getComponentData(page.layout, context, components). For SSG use getPagePaths in getStaticPaths. For preview use context.preview and getPreview/getDesignLibraryData(context.previewData).
+
+## Hard Rules
+
+- Use the single SitecoreClient instance in `src/lib/sitecore-client.ts`. Do not create a second client or instantiate SitecoreClient elsewhere.
+- **Path and locale:** Use `extractPath(context)` (from `@sitecore-content-sdk/nextjs/utils`) to get the path array; use `context.locale` for locale. Do not assume path or locale from elsewhere.
+- **Catch-all page flow:** In getStaticProps/getServerSideProps: `client.getPage(path, { locale: context.locale })`, then `client.getDictionary({ site: page.siteName, locale: page.locale })` and `client.getComponentData(page.layout, context, components)` for component props. Pass the result to the layout renderer.
+- **SSG:** In getStaticPaths, use `client.getPagePaths(siteNames, context?.locales || [])` where site names come from `.sitecore/sites.json` (e.g. `sites.map((s) => s.name)`). Use `revalidate` in getStaticProps for ISR.
+- **Preview:** Use `context.preview` and `context.previewData`; when in preview, use `client.getPreview(context.previewData)` or `client.getDesignLibraryData(context.previewData)`.
+- Config for the client comes from `sitecore.config.ts`; use environment variables, never hardcode secrets.
+
+## Stop Conditions
+
+- Stop if the task requires moving the client to another folder without clear requirement; suggest keeping a single instance in lib.
+- Do not add direct GraphQL or fetch to Layout Service bypassing the client unless the task explicitly requires it.
+- Do not fetch in _app; all data flows from [[...path]].tsx.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for SitecoreClient, getPage, getDictionary, getComponentData, and SSG/SSR.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-multisite-management/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-multisite-management
+description: Handles multisite: site resolution, .sitecore/sites.json, and proxy in src/proxy.ts. Pages Router proxy order is fixed: MultisiteProxy → RedirectsProxy → PersonalizeProxy. Use when working with multiple sites or hostnames.
+---
+
+# Content SDK Multisite Management (Pages Router)
+
+Site resolution from request (e.g. hostname or cookie); proxy rewrites to internal path. No [locale] in URL; Next.js i18n handles locale separately.
+
+## When to Use
+
+- User asks about multiple sites, hostnames, or site resolution.
+- Task involves .sitecore/sites.json, multisite config, or proxy/middleware for site.
+- User mentions "multisite," "site resolution," "hostname," or "sites.json."
+
+## How to perform
+
+- Site list: `.sitecore/sites.json`. Proxy in `src/proxy.ts`; ensure `src/middleware.ts` re-exports it if present. Keep chain order: MultisiteProxy → RedirectsProxy → PersonalizeProxy. Exclude /api, _next, static assets in matcher/skip.
+
+## Hard Rules
+
+- Site list is in `.sitecore/sites.json` (typically generated by Sitecore CLI or deployment). Avoid hand-editing unless the format is known.
+- **Proxy:** Implemented in `src/proxy.ts`. Next.js runs middleware from `middleware.ts` at root or in `src/` — if the app only has `proxy.ts`, add `src/middleware.ts` that re-exports it.
+- **Chain order is fixed:** MultisiteProxy → RedirectsProxy → PersonalizeProxy. **Do not change this order.** MultisiteProxy resolves site from request (hostname or cookie) and rewrites; redirects and personalization run after.
+- **Skip / matcher:** Use the skip callback and matcher to exclude /api, /_next, static files, and health checks so the proxy stays lightweight.
+- Config: sitecore.config.ts → multisite (e.g. enabled, useCookieResolution). Single SitecoreClient; pass resolved site (and locale from context.locale) into getPage, getDictionary, getComponentData.
+
+## Stop Conditions
+
+- Stop if the user wants to reorder the proxy chain; explain that order is required.
+- Stop if sites.json format is unknown and the change could break resolution; suggest checking SDK docs or CLI output.
+- Do not add a second site resolution mechanism; use the existing proxy and config.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for proxy chain, skip, and multisite config.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-route-configuration/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: content-sdk-route-configuration
+description: Configures routing and layout for Pages Router. Single catch-all at src/pages/[[...path]].tsx; path from extractPath(context), locale from context.locale. Data flows via getStaticProps/getServerSideProps to _app and Layout. Use when changing routing, placeholders, or Layout.
+---
+
+# Content SDK Route Configuration (Pages Router)
+
+Single catch-all route; no [site] or [locale] in the URL path. Site is resolved by middleware; locale from Next.js i18n (context.locale).
+
+## When to Use
+
+- User asks to change routing, add a route, or fix 404/500 behavior.
+- Task involves catch-all route, placeholders, _app, or Layout.tsx.
+- User mentions "[[...path]]," "placeholder," "layout," or "getStaticProps."
+
+## How to perform
+
+- Single Sitecore page: `src/pages/[[...path]].tsx`. Use `extractPath(context)` for path and `context.locale` for locale. Fetch all data in getStaticProps/getServerSideProps and pass to _app and Layout. Not-found/error: use getErrorPage in getStaticProps or 404.tsx / _error.tsx as appropriate.
+
+## Hard Rules
+
+- **Single Sitecore page:** `src/pages/[[...path]].tsx`. This is the **only** page that renders Sitecore content. Do not add another page or catch-all for Sitecore content.
+- **Path:** Use `extractPath(context)` (from `@sitecore-content-sdk/nextjs/utils`) to get the path array. **Locale:** Use `context.locale` (Next.js i18n). Do not assume path or locale from headers or elsewhere.
+- **Data flow:** All Sitecore data is fetched in getStaticProps/getServerSideProps in [[...path]].tsx and passed to _app and Layout. Do not fetch Sitecore data in _app.tsx.
+- **Layout:** Layout.tsx renders page layout and placeholders; Providers wrap component props and page context; Bootstrap handles site name and preview mode.
+- Placeholders are rendered by the layout; do not change placeholder names or structure without aligning with Sitecore layout definition.
+- **404 / 500 / _error:** When the catch-all returns `notFound: true`, Next.js renders 404.tsx. For Sitecore-driven error content use `client.getErrorPage(ErrorPage.NotFound)` or `ErrorPage.InternalServerError` in getStaticProps when applicable. _error.tsx is the error boundary; it does not fetch from Sitecore.
+
+## Stop Conditions
+
+- Stop if the user wants to add a second catch-all or a different URL shape for Sitecore pages; explain single-entry-point constraint.
+- Stop if changing proxy/middleware order; order is fixed (MultisiteProxy → RedirectsProxy → PersonalizeProxy).
+- Do not move or rename the catch-all file without updating all references.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for exact paths, extractPath, and layout flow.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-site-setup-and-env/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-site-setup-and-env
+description: Configures site and environment: sitecore.config.ts, environment variables, default site and language. Use when configuring the app or adding env vars. Document in .env.example only; never commit .env or .env.local.
+---
+
+# Content SDK Site Setup and Environment (Pages Router)
+
+Central config in sitecore.config.ts; all secrets and environment-specific values via env vars.
+
+## When to Use
+
+- User asks to configure site, default language, API host, or environment.
+- Task involves sitecore.config.ts, .env, or defaultSite/defaultLanguage.
+- User mentions "config," "environment variables," "API key," or "default site."
+
+## How to perform
+
+- Edit `sitecore.config.ts` with `defineConfig`; read all secrets and env-specific values from `process.env.*`. Add or change vars in `.env.example` (or `.env.remote.example` / `.env.container.example`) with placeholders; never commit `.env` or `.env.local`.
+
+## Hard Rules
+
+- Use `sitecore.config.ts` with `defineConfig` from the SDK. Expose api (edge, local), defaultSite, defaultLanguage, editingSecret, multisite, redirects, personalize as needed.
+- All sensitive or environment-specific values must come from environment variables (e.g. process.env.SITECORE_API_KEY). Never hardcode API keys, secrets, or production URLs in source.
+- Document every new or changed env var in `.env.example` (or `.env.remote.example` / `.env.container.example`). Use placeholder or empty value and a short comment; never put real secrets in example files.
+- Never commit `.env` or `.env.local`; they are gitignored. Example files are the source of truth for which vars exist.
+
+## Stop Conditions
+
+- Stop if the user wants to commit real secrets or production values; insist on env vars and .env.example only.
+- Stop if adding a new env var would require CI or deployment changes without explicit instruction; document the var and note that deployment must set it.
+- Do not edit .next/, node_modules/, or lockfiles unless the task explicitly requires it.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for boundaries and env rules.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-sitemap-robots/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: content-sdk-sitemap-robots
+description: Sitemap and robots.txt for Pages Router: src/pages/api/sitemap.ts and src/pages/api/robots.ts with SitemapMiddleware(scClient, sites).getHandler() and RobotsMiddleware(scClient, sites).getHandler(). Rewrites in next.config.js. Use when configuring sitemap, robots.txt, or SEO.
+---
+
+# Content SDK Sitemap and Robots (Pages Router)
+
+Sitemap and robots.txt are served via **API routes** and rewrites. Use the SDK middleware getHandler pattern and sites from .sitecore/sites.json.
+
+## When to Use
+
+- User asks to add or change sitemap or robots.txt.
+- Task involves SEO, sitemap.xml, or robots route.
+- User mentions "sitemap," "robots," "SEO," or "rewrites."
+
+## How to perform
+
+- Sitemap: `src/pages/api/sitemap.ts` with `SitemapMiddleware(scClient, sites).getHandler()`; robots: `src/pages/api/robots.ts` with `RobotsMiddleware(scClient, sites).getHandler()`. Use sites from `.sitecore/sites.json`. Add rewrites in next.config.js for /sitemap*.xml and /robots.txt to these API routes.
+
+## Hard Rules
+
+- **Sitemap:** `src/pages/api/sitemap.ts` — use `new SitemapMiddleware(scClient, sites).getHandler()`. Export the handler. Use `sites` from `.sitecore/sites.json`.
+- **Robots:** `src/pages/api/robots.ts` — use `new RobotsMiddleware(scClient, sites).getHandler()`. Same pattern.
+- **Rewrites:** In `next.config.js`, add rewrites for `/robots.txt` and `/sitemap*.xml` to the corresponding API routes (e.g. `/sitemap.xml` → `/api/sitemap`).
+- Use the same SitecoreClient instance (e.g. from `src/lib/sitecore-client.ts`) as the rest of the app; do not create a dedicated client for sitemap/robots.
+- Avoid hardcoding the site list; use .sitecore/sites.json.
+
+## Stop Conditions
+
+- Stop if the user wants to serve sitemap/robots from a different origin or with different auth; document and suggest proxy or edge config.
+- Do not add new env vars for sitemap/robots without documenting them in .env.example.
+- Do not change rewrite paths without updating docs and any references.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md) for API routes and rewrites.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-troubleshoot-editing/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: content-sdk-troubleshoot-editing
+description: Troubleshoots XM Cloud editing, preview, and design library for Pages Router. Check context.preview, context.previewData, and editing API routes (config, render, feaas/render). Use when editing or preview does not behave as expected.
+---
+
+# Content SDK Troubleshoot Editing (Pages Router)
+
+This skill focuses on **diagnosing** editing, preview, and design library issues. For implementing editing-safe rendering (context.preview, getPreview/getDesignLibraryData, API routes), use the **content-sdk-editing-safe-rendering** skill; the two are complementary (implementation vs. troubleshooting).
+
+Diagnose and fix editing, preview, and design library issues without breaking the single client or proxy order. This app uses **context.preview** and **context.previewData** in getStaticProps/getServerSideProps.
+
+## When to Use
+
+- User reports that editing, preview, or design library is broken or inconsistent.
+- Task involves debugging "not working in editor," missing chromes, or wrong data in preview.
+- User mentions "editing broken," "preview not working," "design library," or "editor issues."
+
+## How to perform
+
+- Confirm context.preview and context.previewData and correct path/locale (extractPath, context.locale). Verify editing API routes (config, render, feaas/render) are not rewritten (check proxy matcher) and component-map.ts includes the component. Check env (editingSecret, API config) and .env.example documentation.
+
+## Hard Rules
+
+- **Preview flow:** In [[...path]].tsx getStaticProps/getServerSideProps, use `context.preview` and `context.previewData`. When in preview, use `client.getPreview(context.previewData)` or `client.getDesignLibraryData(context.previewData)`. Ensure path and locale come from extractPath(context) and context.locale when not in preview.
+- Editing API routes: `src/pages/api/editing/config.ts` (EditingConfigMiddleware), `render.ts` (EditingRenderMiddleware), `feaas/render.ts` (FEAASRenderMiddleware) must be reachable and use the same component map (`.sitecore/component-map.ts`) and config as the app. Check proxy `config.matcher` so `/api` is excluded and not rewritten or blocked.
+- Check that the component map includes all components used in the layout; missing registration causes "component not found" in editor.
+- Environment: editingSecret and API config must be set (in env); document in .env.example only. Do not log or commit secrets.
+- Common causes: wrong path/locale passed to getPreview/getDesignLibraryData, or component not registered in component-map.ts.
+
+## Stop Conditions
+
+- Stop if the fix would require changing CI, deployment, or XM Cloud project settings; suggest the user do that and document the required env or config.
+- Stop if the issue might be in Sitecore (layout, template) rather than the app; suggest checking layout and content in XM Cloud.
+- Do not recommend disabling security (e.g. skipping secret validation) without explicit user request and warning.
+
+## References
+
+- content-sdk-editing-safe-rendering skill and [AGENTS.md](../../../AGENTS.md) for preview and editing flow.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/.agents/skills/content-sdk-upgrade-assistant/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-sdk-upgrade-assistant
+description: Guides upgrading @sitecore-content-sdk/* packages: version bumps, breaking changes, migration steps. Use when moving to a newer SDK or package version. Check Content SDK repo CHANGELOG and upgrade guides.
+---
+
+# Content SDK Upgrade Assistant (Pages Router)
+
+Upgrade @sitecore-content-sdk/* packages safely; follow the Content SDK repo changelog and migration guides.
+
+## When to Use
+
+- User asks to upgrade SDK packages, update to a new version, or apply a migration.
+- Task involves version bumps, @sitecore-content-sdk/* dependencies, or breaking changes.
+- User mentions "upgrade," "migration," "new version," or "breaking change."
+
+## How to perform
+
+- Bump all @sitecore-content-sdk/* to consistent versions; read the Content SDK repo CHANGELOG (and MIGRATION/upgrade docs) for breaking changes and migration steps. Update package.json, run `npm install` and `npm run build`; test editing and preview after upgrade.
+
+## Hard Rules
+
+- Prefer upgrading all @sitecore-content-sdk/* packages together to a consistent set of versions unless the user requests a partial upgrade. Check peer dependencies and compatibility.
+- Update dependencies in package.json; run `npm install` and `npm run build`. Test editing and preview after upgrade.
+- Read the **Content SDK repository** CHANGELOG (and any MIGRATION.md or upgrade guide) for breaking changes and required code/config updates. Apply migration steps before or with the version bump.
+- Do not edit .next/, node_modules/, or lockfiles unless required for the upgrade. Do not change CI or root tooling unless the task explicitly includes it.
+
+## Stop Conditions
+
+- Stop if the target version is not specified or unclear; ask or suggest checking the Content SDK CHANGELOG and supported versions.
+- Stop if a breaking change requires product or deployment decisions (e.g. new env vars, config schema); list required changes and ask the user to confirm.
+
+## References
+
+- Content SDK repo [CHANGELOG](https://github.com/Sitecore/content-sdk/blob/dev/CHANGELOG.md) and upgrade docs.
+- [AGENTS.md](../../../AGENTS.md) for build commands.
+- [Official Content SDK docs](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html).

package/dist/templates/nextjs/AGENTS.md

@@ -183,6 +183,7 @@ These are the main head-app–specific concepts. Details are in the sections bel
 
 ## References
 
+- **Skills.md** — Capability groupings for this app; [.agents/skills/](.agents/skills/) provides each capability as an Agent Skill (when-to-use, hard rules, stop conditions) for tools that support the [Agent Skills](https://agentskills.io) standard.
 - **CLAUDE.md** — Full coding standards and Sitecore patterns for this template.
 - **.cursor/rules/** — Project and Sitecore rules.
 - [Sitecore Content SDK](https://doc.sitecore.com/xmc/en/developers/content-sdk/sitecore-content-sdk-for-xm-cloud.html) — Official docs.