contentstack · timbenniks-contentstack · Jun 30, 2026
@@ -1 +1,2 @@
 .DS_Store
+.obsidian
@@ -1,6 +1,6 @@
 # Contentstack Skills
 
-A bundle of 21 ready-to-use [Contentstack](https://www.contentstack.com) agent skills for AI coding tools, covering CMS implementation, Brand Kit guidance, delivery SDK development, migration workflows, Developer Hub app architecture, and Launch automation.
+A bundle of 22 ready-to-use [Contentstack](https://www.contentstack.com) agent skills for AI coding tools, covering CMS implementation, Brand Kit guidance, delivery SDK development, kickstart maintenance, migration workflows, Developer Hub app architecture, and Launch automation.
 
 ## What's in here?
 
@@ -21,7 +21,7 @@ You only need to install one. Pick the section below that matches your tool.
 ### Claude Code
 
 ```
-/plugin marketplace add <this-repo>
+/plugin marketplace add contentstack/contentstack-agent-skills
 /plugin install contentstack-skills
 ```
 
@@ -35,16 +35,18 @@ Install via Cursor's plugin marketplace, **or** copy `cursor/rules/*.mdc` into y
 
 Point your agent at this repo or copy the `codex/` directory into your project. The entry point is [`codex/AGENTS.md`](codex/AGENTS.md).
 
+Repository: [github.com/contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills)
+
 ### Gemini CLI
 
 ```
-gemini extensions install <this-repo>
+gemini extensions install contentstack/contentstack-agent-skills
 ```
 
 ### skills CLI (single skill on demand)
 
 ```
-npx skills add <this-repo>@<skill-slug>
+npx skills add contentstack/contentstack-agent-skills@<skill-slug>
 ```
 
 ## Skills included
@@ -68,6 +70,7 @@ npx skills add <this-repo>@<skill-slug>
 | `cms-workflows` | Workflows & Publish Rules | CMS | Workflow stages, approval flows, transition restrictions, publish governance, automation hooks, and common pitfalls. |
 | `developer-hub-app-architect` | Developer Hub App Architect | Developer Hub | Developer Hub and Marketplace app planning, UI location choices, React/TypeScript scaffolding, setup, SDK, manifest, proxy, and publishing issues. |
 | `dx-delivery-sdk` | Delivery SDK | Developer Experience | Production-ready TypeScript with `@contentstack/delivery-sdk` for entries, assets, references, filters, sorting, pagination, locales, Live Preview, and Visual Builder. |
+| `dx-kickstart-next` | Contentstack Kickstart Next | Developer Experience | Maintaining Contentstack's Next.js kickstart: App Router structure, Delivery SDK setup, Live Preview, seeded stack alignment, env vars, validation, and PR reviews. |
 | `dx-migrate-js-to-ts-sdk` | Migrate JS to TS SDK | Developer Experience | Migration from the JavaScript Contentstack SDK to the TypeScript Delivery SDK, including API mapping, rewrites, and unsupported pattern callouts. |
 | `launch-sync-environment-variables-from-env-example` | Sync Launch environment variables from .env.example | Launch | Comparing a local `.env.example` with Launch environment variables and patching missing keys without printing secrets. |
 | `launch-trigger-and-monitor-launch-deployments` | Trigger and Monitor Launch Deployments | Launch | Triggering Launch deployments, polling deployment status, retrieving failure logs, and summarizing likely causes and next steps. |
@@ -92,11 +95,14 @@ skills/CLAUDE.md (router)  ──► cursor/rules/00-router.mdc
 .github/workflows/     CI that regenerates cursor/rules and codex on push
 codex/                 Generated Codex tree — do not edit
 cursor/rules/          Generated Cursor rules — do not edit
+docs/                  Official documentation source for the skills bundle
 scripts/               Contributor build scripts
 skills/                Source of truth — edit here
 gemini-extension.json  Gemini CLI extension manifest
 ```
 
+The `docs/` directory contains the official documentation pages for installation, setup verification, architecture, contributing, and the skill reference.
+
 ## Editing skills
 
 Edit only under `skills/`. Then regenerate the derived trees:

@@ -8,6 +8,7 @@ Use the table below to route a user request to the right skill. Each row maps a
 | Use when users want to migrate, move, switch, port, or re-platform from Contentful to Contentstack, including content models, content, assets, locales, application integrations, website code, migration prerequisites, migration progress checks, or post-migration validation. | [contentstack-migration-companion](./migration-companion/SKILL.md) |
 | Use when a user wants to migrate Contentstack Delivery SDK code from JavaScript to TypeScript. | [dx-migrate-js-to-ts-sdk](./dx-migrate-js-to-ts-sdk/SKILL.md) |
 | Use when a user asks for Contentstack Delivery SDK code, query examples, helper functions, SDK setup, stack initialization, reference inclusion, filtering, sorting, pagination, typed entry fetching, asset fetching, Live Preview setup, Visual Builder support, SSR preview handling, or debugging SDK query chains. | [dx-delivery-sdk](./dx-delivery-sdk/SKILL.md) |
+| Use when working on Contentstack's `kickstart-next` repository or a close fork, including Next.js App Router structure, Contentstack Delivery SDK setup, Live Preview or Visual Builder behavior, seeded stack alignment, environment variables, endpoint or image host configuration, package scripts, validation, CI expectations, or PR review checklists. | [contentstack-kickstart-next](./dx-kickstart-next/SKILL.md) |
 | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](./cms-data-modeling-best-practices/SKILL.md) |
 | Use this skill when a user is implementing or debugging Contentstack Live Preview or Visual Builder, including blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. Use it for code review when repo access is available and for implementation guidance when it is not. | [Live Preview and Visual Builder Support Assistant](./cms-live-preview-visual-builder-support-assistant/SKILL.md) |
 | Use when developers ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. | [Entries](./cms-entries/SKILL.md) |

@@ -0,0 +1,32 @@
+# contentstack-kickstart-next
+
+
+# Contentstack kickstart-next
+
+Use this skill when working in `contentstack/kickstart-next` or a close fork. Inspect the repository first, then load only the matching reference files.
+
+## Routing
+
+1. For App Router routes, React components, client/server boundaries, Tailwind, ESLint, TypeScript, images, or `next.config.mjs`, read [references/next.md](references/next.md).
+2. For Contentstack delivery, preview, Visual Builder, regions, endpoint overrides, env vars, or seeded stack alignment, read [references/contentstack.md](references/contentstack.md).
+3. For content type UIDs, field UIDs, modular blocks, CSLP `$` mappings, or schema-driven renderer/type changes, read [references/content-model.md](references/content-model.md).
+4. For local setup, Contentstack stack seeding, npm scripts, CI, CODEOWNERS, validation commands, docs updates, or PR prep, read [references/workflow.md](references/workflow.md).
+5. For PR/code reviews, severity labels, security checks, or risk checklists, read [references/review.md](references/review.md).
+
+## Default working rules
+
+- Keep guidance grounded in the current checkout. Inspect files before assuming scripts, tests, CI, content types, env vars, or framework conventions exist.
+- Treat kickstarts as user-facing examples: prefer clarity, minimal moving parts, safe defaults, and copyable setup steps over clever abstractions.
+- Preserve Live Preview behavior when changing data fetching, route rendering, components, content types, field UIDs, or Visual Builder bindings.
+- Never commit real Contentstack credentials. Use placeholders in docs and `.env.example`; real values belong in a local gitignored `.env`.
+- When adding or renaming env vars, update `.env.example` and user-facing docs together.
+- When adding remote image sources, update the framework-specific image allowlist or documented env override.
+- When modifying JavaScript or TypeScript files, run `npm run build`; also run `npm run lint` and any `typecheck` script if they exist.
+- Before claiming CI covers something, verify the workflows. If build, lint, or tests are not wired into CI, tell the user to run them locally.
+
+## Response behavior
+
+- For implementation help, give concrete file-level changes and commands.
+- For reviews, separate blockers from major issues and minor nits.
+- For repo setup help, give the shortest successful path first, then optional troubleshooting.
+- If asked to generalize framework-specific guidance later, keep Contentstack behavior in `contentstack.md` and Next.js behavior in `next.md`.
@@ -0,0 +1,48 @@
+# Content model guidance for kickstart-next
+
+Use this before changing Contentstack content type UIDs, field UIDs, `lib/types.ts`, modular block rendering, or Visual Builder/CSLP bindings.
+
+## Seed contract
+
+The app assumes content from `contentstack/kickstart-stack-seed`. Verify the actual stack or seed before making schema claims, but preserve this contract unless the user intentionally changes the model.
+
+| Content type | UID | Used by |
+| --- | --- | --- |
+| Page | `page` | `lib/contentstack.ts` `getPage(url)`, `app/page.tsx`, `components/Page.tsx`, `lib/types.ts` `Page` |
+
+## Page fields
+
+| Field | UID | Type shape in app | Rendered by | Live Preview binding |
+| --- | --- | --- | --- | --- |
+| Title | `title` | `Page.title: string` | `components/Page.tsx` `h1` | `page.$.title` |
+| URL | `url` | `Page.url?: string` | queried by `getPage(url)` | `page.$.url` if rendered later |
+| Description | `description` | `Page.description?: string` | `components/Page.tsx` paragraph | `page.$.description` |
+| Image | `image` | `Page.image?: File \| null` | `next/image` in `components/Page.tsx` | asset `$` mapping, currently `page.image.$.url` |
+| Rich Text | `rich_text` | `Page.rich_text?: string` | sanitized HTML in `components/Page.tsx` | `page.$.rich_text` |
+| Blocks | `blocks` | `Page.blocks?: Blocks[]` | modular block loop in `components/Page.tsx` | `page.$.blocks` and indexed `page.$["blocks__${index}"]` |
+
+## Modular block shape
+
+The `blocks` field contains entries shaped like `{ block: Block }`.
+
+| Block field | UID | Type shape in app | Rendered by | Live Preview binding |
+| --- | --- | --- | --- | --- |
+| Title | `title` | `Block.title?: string` | block `h2` | `block.$.title` |
+| Copy | `copy` | `Block.copy?: string` | sanitized HTML | `block.$.copy` |
+| Image | `image` | `Block.image?: File \| null` | `next/image` | `block.$.image` |
+| Layout | `layout` | `"image_left" \| "image_right" \| null` | flex direction choice | `block.$.layout` if rendered later |
+| Metadata | `_metadata.uid` | key fallback for React list items | list item key | not user-editable |
+
+## Asset shape
+
+- Use the local `File` interface for Contentstack assets.
+- Render images with `file.url` and descriptive alt text from `file.title` or another safe fallback.
+- Keep asset CSLP mappings under `File.$` when the rendered asset field needs Visual Builder editing.
+
+## Change checklist
+
+- If a UID changes, update `getPage`, `lib/types.ts`, renderers, docs, and any Contentstack seed instructions together.
+- If a field is added, add the TypeScript shape, render path, fallback behavior for missing content, and `$` mapping only where the field is editable.
+- If a modular block is added, preserve empty-block editing support with `VB_EmptyBlockParentClass` on the parent block container.
+- If rich text or HTML-like fields are added, sanitize before rendering with `dangerouslySetInnerHTML`.
+- If image fields are added, verify `next.config.mjs` allows the image hostname.
@@ -0,0 +1,48 @@
+# Contentstack guidance for kickstart-next
+
+Use this when changing how `kickstart-next` talks to Contentstack, handles preview, resolves regions/hosts, or aligns with the seeded content model.
+
+## Delivery and preview
+
+- Keep stack configuration and fetching centralized in `lib/contentstack.ts`.
+- Create the stack with `@contentstack/delivery-sdk`, using API key, delivery token, environment, region, optional custom delivery host, and `live_preview` options.
+- Initialize Live Preview with `@contentstack/live-preview-utils` using builder mode, stack SDK/config, stack details, client URL params, and edit button settings.
+- Query the `page` content type by URL when resolving pages. In `kickstart-next`, `getPage(url)` filters `url` with `QueryOperation.EQUALS` and returns the first `Page` entry.
+- When preview mode is enabled, add editable tags with `contentstack.Utils.addEditableTags()` and preserve `$` attributes on entries, fields, and modular blocks.
+
+## Preview versus production
+
+- Preserve the split between production server rendering and preview client refreshes.
+- `app/page.tsx` should fetch `getPage("/")` server-side before branching so both production and preview receive initial content.
+- Preview should render `components/Preview.tsx`, initialize Live Preview client-side, subscribe to entry changes, and refetch the current path.
+
+## Regions and hosts
+
+- Prefer Contentstack endpoint helpers where already used by the repo. Current `kickstart-next` uses `getContentstackEndpoint(region, "", true)` from `@contentstack/utils`.
+- Keep advanced host overrides documented and wired consistently:
+  - Delivery host override: `NEXT_PUBLIC_CONTENTSTACK_CONTENT_DELIVERY` in `kickstart-next`.
+  - Preview host override: `NEXT_PUBLIC_CONTENTSTACK_PREVIEW_HOST` in `kickstart-next`.
+  - Application or Live Preview UI host override: `NEXT_PUBLIC_CONTENTSTACK_CONTENT_APPLICATION` in `kickstart-next`.
+  - Image hostname override: `NEXT_PUBLIC_CONTENTSTACK_IMAGE_HOSTNAME` in `kickstart-next`.
+- If a variable is supported in code but missing from `.env.example` or README setup docs, update the docs/example when touching that area.
+
+## Environment variables
+
+- Required for normal operation: `NEXT_PUBLIC_CONTENTSTACK_API_KEY`, `NEXT_PUBLIC_CONTENTSTACK_DELIVERY_TOKEN`, `NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT`, `NEXT_PUBLIC_CONTENTSTACK_REGION`.
+- Required for preview mode: `NEXT_PUBLIC_CONTENTSTACK_PREVIEW=true` and `NEXT_PUBLIC_CONTENTSTACK_PREVIEW_TOKEN`.
+- Advanced/dedicated-environment overrides: `NEXT_PUBLIC_CONTENTSTACK_CONTENT_DELIVERY`, `NEXT_PUBLIC_CONTENTSTACK_PREVIEW_HOST`, `NEXT_PUBLIC_CONTENTSTACK_CONTENT_APPLICATION`, `NEXT_PUBLIC_CONTENTSTACK_IMAGE_HOSTNAME`.
+- Keep real tokens out of committed files. Use placeholder values in `.env.example`, README snippets, and docs.
+
+## Seed alignment
+
+- Assume the app is aligned to the `contentstack/kickstart-stack-seed` stack unless the repo says otherwise.
+- For a compact schema map, read [content-model.md](content-model.md) before changing content type UIDs, field UIDs, modular blocks, TypeScript entry shapes, or renderer bindings.
+- Changing content type UIDs, field UIDs, or modular block shapes requires matching updates to `lib/types.ts`, renderers, docs, and Live Preview bindings.
+- Preserve the `Page` fields expected by the seed: `title`, `url`, `description`, `image`, `rich_text`, and `blocks`.
+- Preserve modular block support for `block.title`, `block.copy`, `block.image`, `block.layout`, and `_metadata.uid` unless intentionally changing the seed contract.
+- Keep CSLP shapes aligned with the fields rendered in components. `$` mappings are needed on entries, assets, and modular blocks for Visual Builder editing.
+
+## Rendering safety
+
+- Continue sanitizing rich text HTML with `isomorphic-dompurify` before `dangerouslySetInnerHTML`.
+- Keep `VB_EmptyBlockParentClass` on empty modular block containers so Visual Builder can target empty block areas.
@@ -0,0 +1,42 @@
+# Next.js guidance for kickstart-next
+
+Use this when changing the Next.js app, route structure, rendering behavior, images, TypeScript, ESLint, Tailwind, or package scripts.
+
+## App structure
+
+- `app/layout.tsx` is the root layout and imports `app/globals.css`.
+- `app/page.tsx` is the home route. It calls `getPage("/")`, then renders `components/Preview.tsx` when preview is enabled or `components/Page.tsx` otherwise.
+- `components/Preview.tsx` is a Client Component. Keep `"use client"` at the top if it uses hooks or `@contentstack/live-preview-utils` subscriptions.
+- `components/Page.tsx` renders Contentstack fields and is imported elsewhere as `Page`, even though its internal function name may differ.
+- `lib/contentstack.ts` owns Contentstack stack setup, `isPreview`, `initLivePreview()`, and `getPage(url)`.
+- `lib/types.ts` owns TypeScript shapes for Contentstack entries, assets, modular blocks, and CSLP `$` mappings.
+
+## Client/server boundaries
+
+- Fetch initial page data in the route/server component where possible.
+- Use `Preview` only for Live Preview client behavior: initialize preview, subscribe to `ContentstackLivePreview.onEntryChange`, refetch with `getPage(path)`, and unsubscribe on cleanup.
+- Do not move browser-only preview utilities into server-only execution paths.
+
+## Images and rich text
+
+- Use `next/image` for Contentstack images.
+- Keep allowed image hosts in `next.config.mjs` under `images.remotePatterns`.
+- Default image hosts are `images.contentstack.io` and `*-images.contentstack.com`; `NEXT_PUBLIC_CONTENTSTACK_IMAGE_HOSTNAME` can override with a single hostname for custom environments.
+- Sanitize rich text with `isomorphic-dompurify` before using `dangerouslySetInnerHTML`.
+
+## Styling
+
+- The project uses Tailwind CSS 4 via `@tailwindcss/postcss` in `postcss.config.mjs`.
+- `app/globals.css` imports Tailwind with `@import "tailwindcss"` and includes base compatibility styles for Tailwind v4 border defaults.
+- Keep the kickstart visually simple and example-friendly. Avoid adding a design system unless the user explicitly asks for one.
+
+## TypeScript and linting
+
+- `tsconfig.json` uses `strict: true`, `noEmit: true`, `moduleResolution: "bundler"`, and the `@/*` path alias.
+- `eslint.config.mjs` composes Next core web vitals and TypeScript presets.
+- `@typescript-eslint/no-explicit-any` is off in the current config, but prefer precise Contentstack types when practical.
+
+## Package scripts
+
+- Current scripts are usually `dev`, `build`, `start`, and `lint`. Verify `package.json` before telling the user a script exists.
+- There is typically no `typecheck` script; if one is absent, say that type checking is covered by `next build` rather than claiming a separate command ran.