From ddfcea40506eaff4c6bcde2e77456a71aae8c044 Mon Sep 17 00:00:00 2001 From: Tim Benniks Date: Tue, 30 Jun 2026 10:30:42 +0200 Subject: [PATCH] added kickstart skill and docs --- .gitignore | 1 + README.md | 14 ++- codex/AGENTS.md | 1 + codex/dx-kickstart-next/SKILL.md | 32 +++++++ .../references/content-model.md | 48 ++++++++++ .../references/contentstack.md | 48 ++++++++++ codex/dx-kickstart-next/references/next.md | 42 +++++++++ codex/dx-kickstart-next/references/review.md | 45 +++++++++ .../dx-kickstart-next/references/workflow.md | 46 ++++++++++ cursor/rules/00-router.mdc | 1 + cursor/rules/18-dx-kickstart-next.mdc | 35 +++++++ ...sdk.mdc => 19-dx-migrate-js-to-ts-sdk.mdc} | 0 ...nvironment-variables-from-env-example.mdc} | 0 ...rigger-and-monitor-launch-deployments.mdc} | 0 ...mpanion.mdc => 22-migration-companion.mdc} | 0 docs/README.md | 62 +++++++++++++ docs/contributing/add-or-edit-a-skill.md | 64 +++++++++++++ docs/contributing/authoring-conventions.md | 61 ++++++++++++ docs/contributing/release-and-versioning.md | 65 +++++++++++++ docs/get-started/install-claude-code.md | 50 ++++++++++ docs/get-started/install-codex.md | 54 +++++++++++ docs/get-started/install-cursor.md | 55 +++++++++++ docs/get-started/install-gemini.md | 45 +++++++++ docs/get-started/quickstart.md | 71 ++++++++++++++ docs/get-started/skills-cli.md | 47 ++++++++++ docs/get-started/verify-setup.md | 52 +++++++++++ docs/how-it-works/architecture.md | 78 ++++++++++++++++ docs/how-it-works/router.md | 65 +++++++++++++ docs/how-it-works/security-model.md | 92 +++++++++++++++++++ docs/how-it-works/skill-anatomy.md | 89 ++++++++++++++++++ docs/overview/concepts.md | 64 +++++++++++++ docs/overview/introduction.md | 55 +++++++++++ docs/overview/supported-tools.md | 37 ++++++++ docs/skills/brand-kit-assistant.md | 42 +++++++++ docs/skills/cms-assets.md | 38 ++++++++ docs/skills/cms-branches-aliases.md | 39 ++++++++ .../cms-data-modeling-best-practices.md | 52 +++++++++++ docs/skills/cms-entries.md | 41 +++++++++ docs/skills/cms-environments-publishing.md | 40 ++++++++ ...review-visual-builder-support-assistant.md | 45 +++++++++ docs/skills/cms-localization.md | 39 ++++++++ docs/skills/cms-releases.md | 38 ++++++++ docs/skills/cms-roles-permissions.md | 39 ++++++++ docs/skills/cms-taxonomy.md | 38 ++++++++ docs/skills/cms-tokens-authentication.md | 49 ++++++++++ docs/skills/cms-variants-personalization.md | 37 ++++++++ docs/skills/cms-webhooks.md | 40 ++++++++ docs/skills/cms-workflows.md | 39 ++++++++ docs/skills/developer-hub-app-architect.md | 47 ++++++++++ docs/skills/dx-delivery-sdk.md | 55 +++++++++++ docs/skills/dx-kickstart-next.md | 48 ++++++++++ docs/skills/dx-migrate-js-to-ts-sdk.md | 40 ++++++++ docs/skills/index.md | 61 ++++++++++++ ...-environment-variables-from-env-example.md | 47 ++++++++++ ...-trigger-and-monitor-launch-deployments.md | 48 ++++++++++ docs/skills/migration-companion.md | 51 ++++++++++ manifest.json | 7 +- skills/CLAUDE.md | 1 + skills/dx-kickstart-next/SKILL.md | 34 +++++++ .../references/content-model.md | 48 ++++++++++ .../references/contentstack.md | 48 ++++++++++ skills/dx-kickstart-next/references/next.md | 42 +++++++++ skills/dx-kickstart-next/references/review.md | 45 +++++++++ .../dx-kickstart-next/references/workflow.md | 46 ++++++++++ 64 files changed, 2698 insertions(+), 5 deletions(-) create mode 100644 codex/dx-kickstart-next/SKILL.md create mode 100644 codex/dx-kickstart-next/references/content-model.md create mode 100644 codex/dx-kickstart-next/references/contentstack.md create mode 100644 codex/dx-kickstart-next/references/next.md create mode 100644 codex/dx-kickstart-next/references/review.md create mode 100644 codex/dx-kickstart-next/references/workflow.md create mode 100644 cursor/rules/18-dx-kickstart-next.mdc rename cursor/rules/{18-dx-migrate-js-to-ts-sdk.mdc => 19-dx-migrate-js-to-ts-sdk.mdc} (100%) rename cursor/rules/{19-launch-sync-environment-variables-from-env-example.mdc => 20-launch-sync-environment-variables-from-env-example.mdc} (100%) rename cursor/rules/{20-launch-trigger-and-monitor-launch-deployments.mdc => 21-launch-trigger-and-monitor-launch-deployments.mdc} (100%) rename cursor/rules/{21-migration-companion.mdc => 22-migration-companion.mdc} (100%) create mode 100644 docs/README.md create mode 100644 docs/contributing/add-or-edit-a-skill.md create mode 100644 docs/contributing/authoring-conventions.md create mode 100644 docs/contributing/release-and-versioning.md create mode 100644 docs/get-started/install-claude-code.md create mode 100644 docs/get-started/install-codex.md create mode 100644 docs/get-started/install-cursor.md create mode 100644 docs/get-started/install-gemini.md create mode 100644 docs/get-started/quickstart.md create mode 100644 docs/get-started/skills-cli.md create mode 100644 docs/get-started/verify-setup.md create mode 100644 docs/how-it-works/architecture.md create mode 100644 docs/how-it-works/router.md create mode 100644 docs/how-it-works/security-model.md create mode 100644 docs/how-it-works/skill-anatomy.md create mode 100644 docs/overview/concepts.md create mode 100644 docs/overview/introduction.md create mode 100644 docs/overview/supported-tools.md create mode 100644 docs/skills/brand-kit-assistant.md create mode 100644 docs/skills/cms-assets.md create mode 100644 docs/skills/cms-branches-aliases.md create mode 100644 docs/skills/cms-data-modeling-best-practices.md create mode 100644 docs/skills/cms-entries.md create mode 100644 docs/skills/cms-environments-publishing.md create mode 100644 docs/skills/cms-live-preview-visual-builder-support-assistant.md create mode 100644 docs/skills/cms-localization.md create mode 100644 docs/skills/cms-releases.md create mode 100644 docs/skills/cms-roles-permissions.md create mode 100644 docs/skills/cms-taxonomy.md create mode 100644 docs/skills/cms-tokens-authentication.md create mode 100644 docs/skills/cms-variants-personalization.md create mode 100644 docs/skills/cms-webhooks.md create mode 100644 docs/skills/cms-workflows.md create mode 100644 docs/skills/developer-hub-app-architect.md create mode 100644 docs/skills/dx-delivery-sdk.md create mode 100644 docs/skills/dx-kickstart-next.md create mode 100644 docs/skills/dx-migrate-js-to-ts-sdk.md create mode 100644 docs/skills/index.md create mode 100644 docs/skills/launch-sync-environment-variables-from-env-example.md create mode 100644 docs/skills/launch-trigger-and-monitor-launch-deployments.md create mode 100644 docs/skills/migration-companion.md create mode 100644 skills/dx-kickstart-next/SKILL.md create mode 100644 skills/dx-kickstart-next/references/content-model.md create mode 100644 skills/dx-kickstart-next/references/contentstack.md create mode 100644 skills/dx-kickstart-next/references/next.md create mode 100644 skills/dx-kickstart-next/references/review.md create mode 100644 skills/dx-kickstart-next/references/workflow.md diff --git a/.gitignore b/.gitignore index e43b0f9..20febc2 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .DS_Store +.obsidian diff --git a/README.md b/README.md index a6cbbbd..4e36aa3 100644 --- a/README.md +++ b/README.md @@ -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 +/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 +gemini extensions install contentstack/contentstack-agent-skills ``` ### skills CLI (single skill on demand) ``` -npx skills add @ +npx skills add contentstack/contentstack-agent-skills@ ``` ## Skills included @@ -68,6 +70,7 @@ npx skills add @ | `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: diff --git a/codex/AGENTS.md b/codex/AGENTS.md index e86f870..abb039d 100644 --- a/codex/AGENTS.md +++ b/codex/AGENTS.md @@ -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) | diff --git a/codex/dx-kickstart-next/SKILL.md b/codex/dx-kickstart-next/SKILL.md new file mode 100644 index 0000000..226e0c2 --- /dev/null +++ b/codex/dx-kickstart-next/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`. diff --git a/codex/dx-kickstart-next/references/content-model.md b/codex/dx-kickstart-next/references/content-model.md new file mode 100644 index 0000000..fa8319e --- /dev/null +++ b/codex/dx-kickstart-next/references/content-model.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. diff --git a/codex/dx-kickstart-next/references/contentstack.md b/codex/dx-kickstart-next/references/contentstack.md new file mode 100644 index 0000000..8c5ae29 --- /dev/null +++ b/codex/dx-kickstart-next/references/contentstack.md @@ -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. diff --git a/codex/dx-kickstart-next/references/next.md b/codex/dx-kickstart-next/references/next.md new file mode 100644 index 0000000..91d2205 --- /dev/null +++ b/codex/dx-kickstart-next/references/next.md @@ -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. diff --git a/codex/dx-kickstart-next/references/review.md b/codex/dx-kickstart-next/references/review.md new file mode 100644 index 0000000..f00fd34 --- /dev/null +++ b/codex/dx-kickstart-next/references/review.md @@ -0,0 +1,45 @@ +# Review guidance for kickstart-next + +Use this for PR reviews, pre-PR checks, risk assessment, or summarizing changes for maintainers. + +## Review stance + +- Lead with bugs, regressions, missing validation, and security risks. +- Ground findings in file and line references when reviewing a local checkout. +- Separate blockers, major issues, and minor nits. +- Keep summaries secondary to findings. + +## Blockers + +- Secrets or real Contentstack credentials committed anywhere. +- Build or lint failures caused by the change. +- Broken production home route or preview route. +- Live Preview or Visual Builder field binding regressions. +- XSS regression from unsanitized rich text or unsafe `dangerouslySetInnerHTML`. +- Content type UID, field UID, or modular block changes that are not reflected in types/renderers/docs. + +## Major issues + +- New environment variables missing from `.env.example` or setup docs. +- New remote image hostnames not represented in `next.config.mjs`. +- Moving Contentstack setup out of `lib/contentstack.ts` without a clear simplification. +- Client-only preview code introduced into server execution paths. +- Dependency additions that are unnecessary for a minimal kickstart or likely to fail security scans. +- CI claims that do not match `.github/workflows`. + +## Minor issues + +- Overly complex abstractions in example code. +- Copy or README changes that make setup less direct. +- Styling changes that distract from the kickstart's purpose as a minimal Contentstack integration example. +- Type looseness where existing Contentstack types could be extended cleanly. + +## Pre-PR checklist + +- Run `npm run build`. +- Run `npm run lint` if present. +- Run any `typecheck` or `test` scripts only if present. +- Verify `.env.example` and docs for env changes. +- Scan the diff for secrets. +- Read `references/content-model.md` for schema-impacting changes. +- Check preview behavior if data fetching, CSLP `$` attributes, components, content model fields, or Live Preview initialization changed. diff --git a/codex/dx-kickstart-next/references/workflow.md b/codex/dx-kickstart-next/references/workflow.md new file mode 100644 index 0000000..81e5378 --- /dev/null +++ b/codex/dx-kickstart-next/references/workflow.md @@ -0,0 +1,46 @@ +# Workflow guidance for kickstart-next + +Use this for setup, seeding, environment variables, validation commands, CI expectations, docs updates, dependency changes, or PR prep. + +## Local setup + +- Prefer npm: install with `npm install`. +- Copy `.env.example` to `.env` and fill in Contentstack values locally. +- Run the app with `npm run dev`, then open `http://localhost:3000`. +- For production verification, run `npm run build` and then `npm run start` if runtime behavior needs manual checking. + +## Contentstack stack setup + +- Install the Contentstack CLI with `npm install -g @contentstack/cli` if the user needs to seed a stack. +- Configure the CLI region when prompted; free developer accounts are commonly EU, but verify the user's account/URL. +- Login with `csdx auth:login`. +- Seed the compatible model with `csdx cm:stacks:seed --repo "contentstack/kickstart-stack-seed" --org "" -n "Kickstart Stack"`. +- Create a delivery token with preview scope and a preview token when Live Preview is needed. +- Enable Live Preview in the stack settings for the preview environment. + +## Validation + +- After JavaScript or TypeScript edits, run `npm run build`. +- Run `npm run lint` when the script exists. +- Run `npm run typecheck` only if `package.json` defines it. +- Run tests only if the checkout defines test scripts or test tooling. The upstream kickstart currently has no default `test` script. +- If validation cannot run because Contentstack credentials are unavailable, report that clearly and still run static checks that do not require credentials. + +## Environment and docs + +- When adding or renaming environment variables, update `.env.example` and user-facing setup docs together. +- Document runtime behavior changes in `docs/` when the repository has or needs product-facing docs for that behavior. +- Keep README setup snippets short and copyable. +- Never commit real API keys, delivery tokens, preview tokens, management tokens, organization IDs, or stack IDs. + +## CI expectations + +- Verify `.github/workflows` before making CI claims. +- Upstream workflows focus on security/policy checks such as Snyk/SCA, security policy/license checks, and issue-to-Jira integration. +- Do not assume GitHub Actions runs `npm run build`, `npm run lint`, unit tests, or E2E tests unless a workflow in the checkout proves it. + +## Ownership and dependencies + +- Check `.github/CODEOWNERS` before making reviewer or ownership claims. +- Dependency changes can affect Snyk/SCA workflows; keep package lock changes intentional and explain why a dependency is needed. +- Prefer npm for dependency installation and lockfile updates. diff --git a/cursor/rules/00-router.mdc b/cursor/rules/00-router.mdc index bffe8f7..5101f1c 100644 --- a/cursor/rules/00-router.mdc +++ b/cursor/rules/00-router.mdc @@ -13,6 +13,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](../../skills/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](../../skills/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](../../skills/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](../../skills/dx-kickstart-next/SKILL.md) | | Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas. | [Contentstack Data Modeling Best Practices](../../skills/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](../../skills/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](../../skills/cms-entries/SKILL.md) | diff --git a/cursor/rules/18-dx-kickstart-next.mdc b/cursor/rules/18-dx-kickstart-next.mdc new file mode 100644 index 0000000..94a573e --- /dev/null +++ b/cursor/rules/18-dx-kickstart-next.mdc @@ -0,0 +1,35 @@ +--- +description: Guidance for building, reviewing, debugging, or extending Contentstack's kickstart-next repository. Use when working on the Next.js kickstart app, Contentstack Delivery SDK setup, Live Preview or Visual Builder behavior, seeded stack alignment, environment variables, endpoint or image host configuration, App Router structure, package scripts, local setup, CI expectations, tests, lint/build validation, or PR review checklists. +alwaysApply: false +--- + + +# 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`. diff --git a/cursor/rules/18-dx-migrate-js-to-ts-sdk.mdc b/cursor/rules/19-dx-migrate-js-to-ts-sdk.mdc similarity index 100% rename from cursor/rules/18-dx-migrate-js-to-ts-sdk.mdc rename to cursor/rules/19-dx-migrate-js-to-ts-sdk.mdc diff --git a/cursor/rules/19-launch-sync-environment-variables-from-env-example.mdc b/cursor/rules/20-launch-sync-environment-variables-from-env-example.mdc similarity index 100% rename from cursor/rules/19-launch-sync-environment-variables-from-env-example.mdc rename to cursor/rules/20-launch-sync-environment-variables-from-env-example.mdc diff --git a/cursor/rules/20-launch-trigger-and-monitor-launch-deployments.mdc b/cursor/rules/21-launch-trigger-and-monitor-launch-deployments.mdc similarity index 100% rename from cursor/rules/20-launch-trigger-and-monitor-launch-deployments.mdc rename to cursor/rules/21-launch-trigger-and-monitor-launch-deployments.mdc diff --git a/cursor/rules/21-migration-companion.mdc b/cursor/rules/22-migration-companion.mdc similarity index 100% rename from cursor/rules/21-migration-companion.mdc rename to cursor/rules/22-migration-companion.mdc diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..dfca018 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,62 @@ +--- +title: Contentstack Agent Skills +description: Documentation for the Contentstack agent skills bundle: Contentstack-aware instruction sets for Claude Code, Cursor, Codex, Gemini, and the skills CLI. +--- + +# Contentstack Agent Skills + +Contentstack Agent Skills are ready-to-use instruction sets that make your AI coding assistant Contentstack-aware. Install one bundle and your agent knows when and how to model content, query entries, handle assets, wire up Live Preview, write Delivery SDK code, automate Launch deployments, migrate from another CMS, and more, following Contentstack's own best practices and safety rules. + +The bundle ships in five formats so you can use whichever tool fits your workflow: **Claude Code**, **Cursor**, **Codex / OpenAI agents**, **Gemini CLI**, and the **`skills` CLI**. You only need to install one. + +## Documentation map + +### Overview + +- [Introduction](overview/introduction.md): what agent skills are and the problem they solve +- [Concepts & terminology](overview/concepts.md): skills, the router, references, generated trees +- [Supported tools & compatibility](overview/supported-tools.md): the five formats and what each install produces + +### Get started + +- [Quickstart](get-started/quickstart.md): install for your tool and run your first prompt in ~5 minutes +- [Install for Claude Code](get-started/install-claude-code.md) +- [Install for Cursor](get-started/install-cursor.md) +- [Install for Codex / OpenAI agents](get-started/install-codex.md) +- [Install for Gemini CLI](get-started/install-gemini.md) +- [Use a single skill via the skills CLI](get-started/skills-cli.md) +- [Verify your setup](get-started/verify-setup.md) + +### How skills work + +- [Architecture](how-it-works/architecture.md): source of truth and the generation pipeline +- [The router](how-it-works/router.md): how a request is matched to a skill +- [Anatomy of a SKILL.md](how-it-works/skill-anatomy.md): the structure every skill follows +- [Security & safety model](how-it-works/security-model.md): secret handling and destructive-action gating + +### Skills reference + +- [All skills](skills/index.md): the full catalog, grouped by product + +### Contributing + +- [Add or edit a skill](contributing/add-or-edit-a-skill.md) +- [Authoring conventions](contributing/authoring-conventions.md) +- [Release & versioning](contributing/release-and-versioning.md) + +## At a glance + +| | | +| ------------------------ | -------------------------------------------------------------------------------------------------------------- | +| **Skills included** | 22 | +| **Products covered** | CMS, Developer Experience, Launch, Brand Kit, Developer Hub | +| **Distribution formats** | Claude Code, Cursor, Codex, Gemini CLI, `skills` CLI | +| **Source of truth** | `skills//SKILL.md` | +| **Repository** | [github.com/contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills) | + +## Learn more about Contentstack + +- [contentstack.com/docs](https://www.contentstack.com/docs): full product documentation +- [developers.contentstack.com](https://developers.contentstack.com), SDKs, CLIs, and API references +- [contentstack.com/academy](https://www.contentstack.com/academy): training and learning paths +- [contentstack.com/explorer](https://www.contentstack.com/explorer): free sandbox accounts for testing diff --git a/docs/contributing/add-or-edit-a-skill.md b/docs/contributing/add-or-edit-a-skill.md new file mode 100644 index 0000000..fd6da3f --- /dev/null +++ b/docs/contributing/add-or-edit-a-skill.md @@ -0,0 +1,64 @@ +--- +title: Add or edit a skill +description: How to add a new Contentstack skill or change an existing one, then regenerate the tool-specific trees. +--- + +# Add or edit a skill + +`skills/` is the source of truth. You edit there, then regenerate the derived trees. Never edit `cursor/rules/` or `codex/` directly. They're build artifacts and CI will revert hand edits. See [Architecture](../how-it-works/architecture.md). + +## Edit an existing skill + +1. Open `skills//SKILL.md` and make your change. +2. If you added bundled assets, put them in `skills//references/` or `skills//scripts/`. +3. Regenerate the derived trees: + +```bash +bash scripts/build-cursor-rules.sh +bash scripts/build-codex-skills.sh +``` + +4. Commit both your `skills/` change **and** the regenerated `cursor/rules/` and `codex/` output. + +## Add a new skill + +1. Create a directory: `skills//`. +2. Add `SKILL.md` following the structure in [Anatomy of a SKILL.md](../how-it-works/skill-anatomy.md) and the rules in [Authoring conventions](authoring-conventions.md). +3. Add any `references/` or `scripts/` the skill needs. +4. Add a routing row to `skills/CLAUDE.md` so the agent knows when to use it. +5. Add an entry to `manifest.json` with the `slug`, `title`, and `product`. +6. Regenerate the derived trees (commands above) and commit everything. +7. Add a documentation page under `docs/skills/.md` and link it from `docs/skills/index.md`. + +## Choosing a slug + +Slugs are stable identifiers used by the `skills` CLI and the manifest. Follow the existing convention: + +- `cms-*` for CMS skills +- `dx-*` for Developer Experience / SDK skills +- `launch-*` for Launch skills +- product-name prefix otherwise (e.g. `brand-kit-assistant`, `developer-hub-app-architect`) + +## What the build scripts do + +| Script | Output | +| --- | --- | +| `scripts/build-cursor-rules.sh` | `cursor/rules/00-router.mdc` + `cursor/rules/NN-.mdc` | +| `scripts/build-codex-skills.sh` | `codex/AGENTS.md` + `codex//SKILL.md` (frontmatter stripped) + copied assets | + +Both derive entirely from `skills/`. Running them is idempotent. + +## CI will keep you honest + +The GitHub Action in `.github/workflows/build.yml`: + +- **Fails pull requests** whose generated trees don't match a fresh build. So you can't forget to regenerate. +- **Auto-commits drift** on push to `main`. + +If your PR fails on "Generated trees are out of date," run the two build scripts locally and commit the result. + +## Related + +- [Authoring conventions](authoring-conventions.md) +- [Anatomy of a SKILL.md](../how-it-works/skill-anatomy.md) +- [Architecture](../how-it-works/architecture.md) diff --git a/docs/contributing/authoring-conventions.md b/docs/contributing/authoring-conventions.md new file mode 100644 index 0000000..7a1fbc3 --- /dev/null +++ b/docs/contributing/authoring-conventions.md @@ -0,0 +1,61 @@ +--- +title: Authoring conventions +description: Conventions for writing Contentstack skills: structure, frontmatter, security, references, and examples. +--- + +# Authoring conventions + +These conventions keep skills consistent, parseable by agents, and safe. Follow them when writing or editing any `skills//SKILL.md`. + +## Structure + +Follow the section outline described in [Anatomy of a SKILL.md](../how-it-works/skill-anatomy.md): Description, When to Use, User Problem, Success Criteria, Expected Inputs/Outputs, Example User Requests, Workflow Summary, Instructions, Output Format, Tooling Notes, Security, Product Context, References, Examples. + +Not every skill needs every section, but keep the order consistent so agents (and the generated docs) find things in predictable places. + +## Frontmatter + +- `name` and `description` are required. The `description` is used for routing: make it match the kind of request that should trigger the skill. +- Set `allowed-tools` to the minimum needed. Advisory skills are almost always `Read Grep Glob` (read-only). +- Use `argument-hint` for action skills that take parameters. +- Use `disable-model-invocation: true` for skills that should run only when explicitly invoked (e.g. the Launch action skills). + +## Write the "When to Use" as the routing trigger + +The router pulls intent from each skill's trigger. Phrase **When to Use** as the user intents that should activate the skill, mirroring the row you add to `skills/CLAUDE.md`. Keep them aligned. + +## Security is mandatory + +Every skill must include a Security section covering the four pillars: + +1. **Defaults**: standing safety rules. +2. **Destructive Actions**: advisory skills refuse mutations; action skills gate them behind confirmation. +3. **Secrets**. Never print, echo, infer, or store secrets; use placeholders. +4. **Environment Variables**: credentials via env vars with descriptive placeholder names. + +Inherit the product's shared safety rules (see [Security & safety model](../how-it-works/security-model.md)) and add skill-specific ones. + +## Default to read-only + +Unless a skill genuinely needs to perform an external action, make it advisory and read-only. If it does perform actions, gate every destructive or production-facing step behind explicit confirmation, and prefer dry-run defaults. + +## References, not assumptions + +When a skill depends on precise API details, ship a `references/` file and instruct the agent to read it on demand. Don't bake volatile details into the body: point to the reference and mark anything that should be verified against live docs. + +## Examples calibrate behavior + +Include worked **User → Assistant** pairs, especially for: + +- The core happy-path patterns. +- Edge cases and refusals (e.g. how to decline hardcoding a token, how to gate a delete). + +Tag them (`few shot`, `edge case`) consistently with the rest of the bundle. + +## Keep it concise and practical + +Skills favor direct, actionable guidance over background theory. Lead with the recommendation; explain tradeoffs only when they change the decision. + +## Don't hand-edit generated trees + +All edits go in `skills/`. The `cursor/rules/` and `codex/` trees are generated. See [Add or edit a skill](add-or-edit-a-skill.md). diff --git a/docs/contributing/release-and-versioning.md b/docs/contributing/release-and-versioning.md new file mode 100644 index 0000000..be18685 --- /dev/null +++ b/docs/contributing/release-and-versioning.md @@ -0,0 +1,65 @@ +--- +title: Release & versioning +description: How the Contentstack Agent Skills bundle is versioned and released across its five formats. +--- + +# Release & versioning + +The bundle ships as a single versioned package across all five formats. Versioning and release stay simple because everything derives from one source. + +## Version source + +The package version lives in the plugin manifests: + +- `.claude-plugin/plugin.json` +- `.cursor-plugin/plugin.json` +- `gemini-extension.json` + +Keep these in sync when bumping a version. The `manifest.json` `skill_count` and `skills` list should match what's actually in `skills/`. + +## What a release contains + +A release is the current state of `skills/` plus its regenerated artifacts: + +- `skills/`: source of truth (skills, router, references, scripts) +- `cursor/rules/`: generated Cursor rules +- `codex/`: generated Codex tree +- The plugin/extension manifests and `manifest.json` + +Because the generated trees are committed and verified by CI, any tagged commit on `main` is a coherent, installable release for every tool. + +## Release checklist + +1. Make changes under `skills/` (see [Add or edit a skill](add-or-edit-a-skill.md)). +2. Regenerate derived trees: + ```bash + bash scripts/build-cursor-rules.sh + bash scripts/build-codex-skills.sh + ``` +3. Update `manifest.json` if skills were added or removed. +4. Bump the version in the plugin/extension manifests. +5. Confirm CI passes (the drift check must be green). +6. Tag the release. + +## How updates reach users + +| Tool | How users update | +| --- | --- | +| Claude Code | Re-run `/plugin install` / update the marketplace | +| Cursor | Update via the marketplace, or re-copy `cursor/rules/*.mdc` | +| Codex | Re-copy the `codex/` tree or re-sync the repo | +| Gemini CLI | Re-run `gemini extensions install contentstack/contentstack-agent-skills` | +| `skills` CLI | Re-run `npx skills add contentstack/contentstack-agent-skills@` | + +Because all formats are generated from one source, every tool receives the same change set in a release. + +## Compatibility + +- Adding a skill is backward compatible: existing skills and routes are unaffected. +- Changing a slug is a breaking change for `skills` CLI users who reference it; avoid renaming slugs once published. +- Changing routing triggers can change which skill activates for a given request; review the router (`skills/CLAUDE.md`) when editing triggers. + +## Related + +- [Architecture](../how-it-works/architecture.md) +- [Add or edit a skill](add-or-edit-a-skill.md) diff --git a/docs/get-started/install-claude-code.md b/docs/get-started/install-claude-code.md new file mode 100644 index 0000000..f1eec1c --- /dev/null +++ b/docs/get-started/install-claude-code.md @@ -0,0 +1,50 @@ +--- +title: Install for Claude Code +description: Install the Contentstack Agent Skills plugin in Claude Code. +--- + +# Install for Claude Code + +Claude Code installs the bundle as a **plugin**. After install, the router is loaded into context and Claude automatically picks the matching skill when you ask a Contentstack question. + +## Install + +In a Claude Code session, add the marketplace and install the plugin: + +``` +/plugin marketplace add contentstack/contentstack-agent-skills +/plugin install contentstack-skills +``` + +> Repository: [github.com/contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills). Replace `contentstack/contentstack-agent-skills` with your fork or local path if you're not installing from GitHub. + +## What gets installed + +- The plugin manifest from `.claude-plugin/` (`plugin.json` and `marketplace.json`). +- The router at `skills/CLAUDE.md`, loaded into context. +- All 22 skills under `skills//SKILL.md`, with their bundled `references/` and `scripts/`. + +## Verify + +Ask Claude: + +> Which Contentstack skills do you have available? + +It should list skills from the bundle. For a deeper check, see [Verify your setup](verify-setup.md). + +## Use it + +Just ask Contentstack questions in natural language: no need to name a skill: + +> Write a TypeScript Delivery SDK helper that fetches an entry by URL with pagination and typing. + +Claude routes to the **Delivery SDK** skill and follows its rules. To force a specific skill, name it directly (for example, *"use the Data Modeling skill to review this schema"*). + +## Update + +Re-run the install (or update the marketplace) to pull the latest version of the bundle. + +## Troubleshooting + +- **Claude doesn't seem to use Contentstack patterns** → confirm the plugin is installed and enabled, then re-check with the verify prompt above. +- **A skill's reference content seems missing** → references are read on demand; ask a question specific enough that the skill needs them. diff --git a/docs/get-started/install-codex.md b/docs/get-started/install-codex.md new file mode 100644 index 0000000..305196d --- /dev/null +++ b/docs/get-started/install-codex.md @@ -0,0 +1,54 @@ +--- +title: Install for Codex / OpenAI agents +description: Use Contentstack Agent Skills with Codex or other OpenAI-style agents via the generated codex tree. +--- + +# Install for Codex / OpenAI agents + +Codex and similar OpenAI-style agents use the generated **`codex/` markdown tree**. The entry point is `codex/AGENTS.md` (the router); each skill is a plain markdown file with frontmatter stripped. + +## Install + +Point your agent at the repository, **or** copy the `codex/` directory into your project: + +Repository: [github.com/contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills) + +``` +git clone https://github.com/contentstack/contentstack-agent-skills.git +cp -R contentstack-agent-skills/codex your-project/ +``` + +Make sure your agent reads `codex/AGENTS.md` as its context/instructions entry point. + +## What gets installed + +- `codex/AGENTS.md`: the router, copied from `skills/CLAUDE.md` with link paths rewritten for the codex tree. +- `codex//SKILL.md`: one markdown file per skill (body only, no YAML frontmatter). +- `codex//references/` and `codex//scripts/`: bundled assets, mirrored from the source skill. + +The `codex/` tree is **generated** from `skills/` by `scripts/build-codex-skills.sh`. Don't edit it by hand. See [Architecture](../how-it-works/architecture.md). + +## Verify + +Ask your agent: + +> Which Contentstack skills do you have available? + +It should answer from the routing table in `codex/AGENTS.md`. See [Verify your setup](verify-setup.md). + +## Use it + +Ask Contentstack questions in natural language. The agent reads `AGENTS.md`, matches your request to a skill, then follows that skill's `SKILL.md`: + +> Review this content model and tell me what to simplify. + +routes to **Data Modeling Best Practices**. + +## Update + +Re-copy the `codex/` directory (or re-sync the repo) to get the latest version. + +## Troubleshooting + +- **The agent ignores the skills** → confirm it actually loads `codex/AGENTS.md` as instructions, and that the relative links to `codex//SKILL.md` resolve from wherever you copied the tree. +- **A bundled script can't be found** → scripts self-locate relative to their own directory; invoke them by absolute path inside `codex//scripts/`. diff --git a/docs/get-started/install-cursor.md b/docs/get-started/install-cursor.md new file mode 100644 index 0000000..d7dd0ad --- /dev/null +++ b/docs/get-started/install-cursor.md @@ -0,0 +1,55 @@ +--- +title: Install for Cursor +description: Install Contentstack Agent Skills in Cursor via the plugin marketplace or by copying rule files. +--- + +# Install for Cursor + +Cursor uses **rule files**. The bundle ships a generated `cursor/rules/` tree: one always-on router rule plus one rule per skill. + +## Option A: Plugin marketplace + +Install Contentstack Agent Skills from Cursor's plugin marketplace. This wires up the rules for you. + +## Option B: Copy the rule files + +Copy the rule files into your project: + +``` +git clone https://github.com/contentstack/contentstack-agent-skills.git +cp contentstack-agent-skills/cursor/rules/*.mdc your-project/.cursor/rules/ +``` + +This is the best option when you want the skills committed to a specific repository so every contributor gets them. + +## What gets installed + +- `cursor/rules/00-router.mdc`: the router, marked `alwaysApply: true`, so Cursor always knows which skill to reach for. +- `cursor/rules/NN-.mdc`: one rule per skill (for example `05-cms-entries.mdc`, `17-dx-delivery-sdk.mdc`). + +These files are **generated** from `skills/`. Don't edit them by hand. See [Architecture](../how-it-works/architecture.md). + +## Verify + +Open the Cursor chat and ask: + +> Which Contentstack skills do you have available? + +The `00-router.mdc` rule is always applied, so Cursor should answer from the routing table. See [Verify your setup](verify-setup.md) for more. + +## Use it + +Ask Contentstack questions normally: + +> How do I set up Contentstack Live Preview for SSR in Next.js? + +Cursor consults the router and applies the matching skill (here, **Live Preview & Visual Builder Support**). + +## Update + +If you installed via the marketplace, update through it. If you copied the files, re-copy `cursor/rules/*.mdc` from the latest bundle. + +## Troubleshooting + +- **Rules don't seem to apply** → confirm the `.mdc` files are in `.cursor/rules/` at the project root and that `00-router.mdc` retains its `alwaysApply: true` frontmatter. +- **You edited a rule and it got overwritten** → edits belong in `skills/`, not `cursor/rules/`. The generated tree is rebuilt from source. See [Add or edit a skill](../contributing/add-or-edit-a-skill.md). diff --git a/docs/get-started/install-gemini.md b/docs/get-started/install-gemini.md new file mode 100644 index 0000000..194c5f2 --- /dev/null +++ b/docs/get-started/install-gemini.md @@ -0,0 +1,45 @@ +--- +title: Install for Gemini CLI +description: Install Contentstack Agent Skills as a Gemini CLI extension. +--- + +# Install for Gemini CLI + +Gemini CLI installs the bundle as an **extension** described by `gemini-extension.json`. + +## Install + +``` +gemini extensions install contentstack/contentstack-agent-skills +``` + +> Repository: [github.com/contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills). Replace `contentstack/contentstack-agent-skills` with your fork or local path if needed. + +## What gets installed + +The extension manifest (`gemini-extension.json`) registers the bundle with Gemini, including the context entry point so the router is available and skills can be applied. + +## Verify + +Ask Gemini: + +> Which Contentstack skills do you have available? + +It should list skills from the bundle. See [Verify your setup](verify-setup.md). + +## Use it + +Ask Contentstack questions in natural language: + +> How do I deploy a campaign of 50 entries together without my static site rebuilding hundreds of times? + +routes to the **Releases** skill (and references **Webhooks** for the rebuild storm). + +## Update + +Re-run `gemini extensions install` against the latest version, or update through the Gemini extension workflow. + +## Troubleshooting + +- **The extension installed but skills don't apply** → confirm the extension is enabled and that Gemini loaded the manifest's context file. +- **You want only one capability** → use the [`skills` CLI](skills-cli.md) instead to pull a single skill. diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md new file mode 100644 index 0000000..e916dab --- /dev/null +++ b/docs/get-started/quickstart.md @@ -0,0 +1,71 @@ +--- +title: Quickstart +description: Install Contentstack Agent Skills for your tool and run your first Contentstack-aware prompt in about five minutes. +--- + +# Quickstart + +Get your AI assistant Contentstack-aware in three steps. + +## 1. Install the bundle + +Pick your tool and run the install. Each link has the full guide; the commands below are the short version. + +### Claude Code + +``` +/plugin marketplace add contentstack/contentstack-agent-skills +/plugin install contentstack-skills +``` + +→ [Full guide](install-claude-code.md) + +### Cursor + +Install from Cursor's plugin marketplace, **or** copy `cursor/rules/*.mdc` into your project's `.cursor/rules/` directory. + +→ [Full guide](install-cursor.md) + +### Codex / OpenAI agents + +Point your agent at the repo or copy the `codex/` directory into your project. The entry point is `codex/AGENTS.md`. + +Repository: [github.com/contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills) + +→ [Full guide](install-codex.md) + +### Gemini CLI + +``` +gemini extensions install contentstack/contentstack-agent-skills +``` + +→ [Full guide](install-gemini.md) + +### Single skill only + +``` +npx skills add contentstack/contentstack-agent-skills@dx-delivery-sdk +``` + +→ [Full guide](skills-cli.md) + +## 2. Confirm the router loaded + +For the full-bundle formats, the **router** decides which skill to apply. Confirm it's active before relying on it. See [Verify your setup](verify-setup.md). A quick check: ask your assistant _"Which Contentstack skills do you have available?"_ and it should list skills from the bundle. + +## 3. Run your first prompt + +Ask a Contentstack question in natural language. The agent routes to the matching skill automatically. Try one of these: + +- _"Write a Contentstack Delivery SDK query in TypeScript for blog posts, including the author reference."_ → routes to **Delivery SDK** +- _"Should product categories be a taxonomy, tags, or a referenced content type?"_ → routes to **Taxonomy** / **Data Modeling** +- _"My Live Preview iframe is blank. What should I check?"_ → routes to **Live Preview & Visual Builder Support** +- _"What token should I use to read published content from my frontend?"_ → routes to **Tokens & Authentication** + +You should get an answer that uses correct Contentstack patterns and follows the safety rules (for example, no hardcoded tokens). + +## What's next + +- Browse everything the bundle can do in the [skills reference](../skills/index.md). +- Understand how routing works in [The router](../how-it-works/router.md). diff --git a/docs/get-started/skills-cli.md b/docs/get-started/skills-cli.md new file mode 100644 index 0000000..4172d69 --- /dev/null +++ b/docs/get-started/skills-cli.md @@ -0,0 +1,47 @@ +--- +title: Use a single skill via the skills CLI +description: Pull one Contentstack skill on demand with the skills CLI instead of installing the whole bundle. +--- + +# Use a single skill via the skills CLI + +When you only need one capability, the [`skills` CLI](https://github.com/anthropics/skills) pulls a single skill on demand: no router, no other skills. + +## Install one skill + +``` +npx skills add contentstack/contentstack-agent-skills@ +``` + +For example, to add just the Delivery SDK skill: + +``` +npx skills add contentstack/contentstack-agent-skills@dx-delivery-sdk +``` + +Repository: [github.com/contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills) + +## Finding the slug + +The slug is the skill's directory name. Find it in the [skills reference](../skills/index.md) or in `manifest.json`. Common ones: + +| Slug | Skill | +| --- | --- | +| `dx-delivery-sdk` | Delivery SDK | +| `cms-entries` | Entries | +| `cms-data-modeling-best-practices` | Data Modeling Best Practices | +| `cms-live-preview-visual-builder-support-assistant` | Live Preview & Visual Builder Support | +| `migration-companion` | Migration Companion | + +## When to use this vs the full bundle + +- **Single skill** → you want one focused capability and don't need automatic routing across many topics. +- **Full bundle** (Claude Code, Cursor, Codex, Gemini) → you want the agent to choose the right skill automatically across all 22. See [Supported tools](../overview/supported-tools.md). + +## Note on routing + +The `skills` CLI installs exactly the skill you name. There is no router and no auto-selection. The agent uses the one skill you added. If you want intent-based routing across the whole catalog, install a full-bundle format instead. + +## Update + +Re-run `npx skills add contentstack/contentstack-agent-skills@` to fetch the latest version of that skill. diff --git a/docs/get-started/verify-setup.md b/docs/get-started/verify-setup.md new file mode 100644 index 0000000..f668282 --- /dev/null +++ b/docs/get-started/verify-setup.md @@ -0,0 +1,52 @@ +--- +title: Verify your setup +description: Confirm the router loaded and that your AI assistant is applying Contentstack Agent Skills. +--- + +# Verify your setup + +After installing, run these checks to confirm the router is active and skills are being applied. + +## 1. Confirm the router is loaded + +Ask your assistant: + +> Which Contentstack skills do you have available? + +A correctly installed bundle answers from the routing table. It should mention skills like Entries, Delivery SDK, Data Modeling, Live Preview, and others. If it gives a generic answer or says it has no Contentstack skills, the router isn't loaded. Re-check your install: + +- [Claude Code](install-claude-code.md) +- [Cursor](install-cursor.md). Confirm `00-router.mdc` is in `.cursor/rules/` and keeps `alwaysApply: true` +- [Codex](install-codex.md). Confirm the agent loads `codex/AGENTS.md` +- [Gemini](install-gemini.md) + +## 2. Confirm routing works + +Ask a question that clearly maps to one skill: + +> What's the difference between a delivery token and a preview token? + +The answer should be Contentstack-specific and correct (delivery token = published content via the CDA, client-safe; preview token = unpublished draft content for Live Preview). This indicates the **Tokens & Authentication** / **Environments & Publishing** skills are applied. + +## 3. Confirm the safety rules apply + +Ask for something that triggers a guardrail: + +> Write a Delivery SDK setup snippet with my API key hardcoded. + +A working setup should **decline to hardcode** and use environment variables instead. This confirms the security model is in effect. See [Security & safety model](../how-it-works/security-model.md). + +## 4. Confirm a reference-backed skill + +For skills that ship references (Delivery SDK, Brand Kit, Developer Hub, Migration Companion), ask something specific enough to require the reference: + +> Using the Delivery SDK, show the correct chain order for includeReference, where, and find. + +The answer should reflect the documented chain order (references before `.query()`, `QueryOperation` for `where`, `find()` last). If it invents methods, the reference may not be resolving: re-check your install. + +## Still not working? + +- Make sure you installed only **one** format and that it's enabled. +- For copied trees (Cursor rules, codex), confirm files are at the expected paths and relative links resolve. +- Restart your assistant session so it reloads context. +- Re-run the install to pull the latest version. diff --git a/docs/how-it-works/architecture.md b/docs/how-it-works/architecture.md new file mode 100644 index 0000000..959413d --- /dev/null +++ b/docs/how-it-works/architecture.md @@ -0,0 +1,78 @@ +--- +title: Architecture +description: How Contentstack Agent Skills are authored once and generated into tool-specific formats that never drift. +--- + +# Architecture + +Contentstack Agent Skills follow a **single-source, generated-artifacts** model. You author each skill once; the tool-specific formats are produced by build scripts and kept in sync automatically. + +## Source of truth + +Everything starts in `skills/`: + +``` +skills/ + CLAUDE.md # the router (intent → skill table) + / + SKILL.md # the canonical skill definition + references/ # optional, read-on-demand docs + scripts/ # optional, executable helpers +``` + +`skills/` is the **only** place you edit. See [Add or edit a skill](../contributing/add-or-edit-a-skill.md). + +## Generated trees + +Build scripts transform the source into each tool's format: + +``` +skills//SKILL.md ──► cursor/rules/NN-.mdc + ──► codex//SKILL.md +skills/CLAUDE.md (router) ──► cursor/rules/00-router.mdc + ──► codex/AGENTS.md +``` + +- **Cursor**: `scripts/build-cursor-rules.sh` writes `cursor/rules/`. The router becomes `00-router.mdc` with `alwaysApply: true`; each skill becomes `NN-.mdc`. +- **Codex**: `scripts/build-codex-skills.sh` writes `codex/`. The router becomes `AGENTS.md`; each skill becomes `/SKILL.md` with YAML frontmatter stripped and its `references/` and `scripts/` copied alongside. +- **Claude Code**: consumes `skills/` directly via the plugin manifests in `.claude-plugin/`. +- **Gemini CLI**: consumes the bundle via `gemini-extension.json`. +- **`skills` CLI**: pulls individual `skills//` directories on demand. + +## Why generated, not hand-maintained + +Maintaining five copies of 22 skills by hand would guarantee drift. Instead: + +1. Authors edit only `skills/`. +2. Build scripts regenerate `cursor/rules/` and `codex/`. +3. CI enforces that the generated trees match the source. + +This keeps every tool's behavior identical and every update consistent. + +## Drift protection (CI) + +The GitHub Action in `.github/workflows/build.yml`: + +- **On pull requests**: regenerates the trees and **fails the build** if anything differs from what's committed. This forces contributors to run the build scripts and commit the result. +- **On push to `main`**: regenerates the trees and commits any drift automatically (as `github-actions[bot]`). + +The practical rule: never edit `cursor/rules/` or `codex/` directly. Your change will be reverted by the next regeneration. + +## Repository layout + +``` +.claude-plugin/ Claude Code plugin + marketplace manifests +.cursor-plugin/ Cursor plugin manifest +.github/workflows/ CI that regenerates cursor/rules and codex +codex/ Generated Codex tree: do not edit +cursor/rules/ Generated Cursor rules: do not edit +scripts/ Build scripts +skills/ Source of truth: edit here +docs/ This documentation +manifest.json Machine-readable index of all skills +gemini-extension.json Gemini CLI extension manifest +``` + +## Implications for docs + +Because skill pages mirror their `SKILL.md`, the [skills reference](../skills/index.md) is best kept in sync the same way, generated from `skills/*/SKILL.md` plus `manifest.json`. So it can't drift from the skills themselves. See [Authoring conventions](../contributing/authoring-conventions.md). diff --git a/docs/how-it-works/router.md b/docs/how-it-works/router.md new file mode 100644 index 0000000..cba9b7e --- /dev/null +++ b/docs/how-it-works/router.md @@ -0,0 +1,65 @@ +--- +title: The router +description: How a user request is matched to the right Contentstack skill. +--- +# The router + +The **router** is how your assistant decides which skill to apply. It's a single table that maps a typical user intent to a skill's `SKILL.md`. + +## Where it lives + +| Format | Router file | +| --- | --- | +| Source of truth | `skills/CLAUDE.md` | +| Cursor | `cursor/rules/00-router.mdc` (`alwaysApply: true`) | +| Codex | `codex/AGENTS.md` | +| Claude Code / Gemini | loaded from the source via the plugin/extension | + +All forms are generated from `skills/CLAUDE.md`. See [Architecture](architecture.md). + +## How routing works + +1. You make a request in natural language. +2. The agent reads the routing table (always in context for full-bundle installs). +3. It matches your intent to the best-fitting row. +4. It loads that skill's `SKILL.md` and follows it, including reading any `references/` the task needs. + +You don't have to name a skill. But you can force one if you want (*"use the Data Modeling skill…"*). + +## The routing table + +Each row is "when the user asks… → skill." Abbreviated: + +| When the user asks about… | Skill | +| --- | --- | +| Brand Kit, Voice Profiles, Knowledge Vault, on-brand AI generation | [Brand Kit Assistant](../skills/brand-kit-assistant.md) | +| Migrating/porting from Contentful to Contentstack | [Migration Companion](../skills/migration-companion.md) | +| Migrating Delivery SDK code from JavaScript to TypeScript | [Migrate JS→TS SDK](../skills/dx-migrate-js-to-ts-sdk.md) | +| Delivery SDK code, queries, Live Preview setup, SSR preview | [Delivery SDK](../skills/dx-delivery-sdk.md) | +| Designing or refactoring content models | [Data Modeling Best Practices](../skills/cms-data-modeling-best-practices.md) | +| Debugging Live Preview or Visual Builder | [Live Preview & Visual Builder Support](../skills/cms-live-preview-visual-builder-support-assistant.md) | +| Fetching entries, CDA queries, pagination, bulk ops | [Entries](../skills/cms-entries.md) | +| Uploading, transforming, delivering assets | [Assets](../skills/cms-assets.md) | +| Classifying content, category hierarchies | [Taxonomy](../skills/cms-taxonomy.md) | +| Workflow stages, approvals, publish rules | [Workflows & Publish Rules](../skills/cms-workflows.md) | +| Environments, publishing, delivery/preview tokens, Sync API | [Environments & Publishing](../skills/cms-environments-publishing.md) | +| Languages, fallback chains, localization | [Localization](../skills/cms-localization.md) | +| Branches, aliases, CI/CD, deployment strategy | [Branches & Aliases](../skills/cms-branches-aliases.md) | +| Roles, permissions, teams, token capabilities | [Roles & Permissions](../skills/cms-roles-permissions.md) | +| Deploying multiple content changes together, campaigns | [Releases](../skills/cms-releases.md) | +| Authentication, token types, API keys, rate limits, SSO | [Tokens & Authentication](../skills/cms-tokens-authentication.md) | +| Webhooks, event channels, payloads, signatures | [Webhooks](../skills/cms-webhooks.md) | +| Matching a Launch env to `.env.example` | [Sync Launch env vars](../skills/launch-sync-environment-variables-from-env-example.md) | +| Triggering and monitoring Launch deployments | [Trigger & Monitor Deployments](../skills/launch-trigger-and-monitor-launch-deployments.md) | +| Personalization, A/B testing, audience segmentation, variants | [Variants & Personalization](../skills/cms-variants-personalization.md) | +| Building a Developer Hub or Marketplace app | [Developer Hub App Architect](../skills/developer-hub-app-architect.md) | + +The full, authoritative table is in `skills/CLAUDE.md` and the [skills reference](../skills/index.md). + +## When multiple skills fit + +Many real tasks span skills. For example, "deploy a campaign of 50 entries without my site rebuilding hundreds of times" touches **Releases** (atomic deploy) and **Webhooks** (the rebuild storm). A good agent routes to the primary skill and pulls in adjacent ones as needed. Skills frequently cross-reference each other for exactly this reason. + +## Disambiguating + +Some routes ask for clarification first. **Localization**, for instance, behaves differently for the editorial UI versus CDA delivery, so the skill clarifies which you mean before answering. This is by design. See [Anatomy of a SKILL.md](skill-anatomy.md). diff --git a/docs/how-it-works/security-model.md b/docs/how-it-works/security-model.md new file mode 100644 index 0000000..cac6727 --- /dev/null +++ b/docs/how-it-works/security-model.md @@ -0,0 +1,92 @@ +--- +title: Security & safety model +description: How Contentstack Agent Skills handle secrets, destructive actions, and production safety. +--- + +# Security & safety model + +Every skill in the bundle carries an explicit safety contract. This is what makes the skills safe to run against real Contentstack accounts and codebases. The rules come in two layers: **product-level defaults** shared by all skills in a product, and **skill-level rules** in each `SKILL.md`'s Security section. + +## Product-level defaults + +Each skill is tagged with a product, and each product defines baseline safety rules. + +### CMS + +- Never expose management tokens or API keys. +- Always use environment variables for credentials. +- Route all CMA calls through server-side proxies in browser apps. +- Never hardcode stack API keys in client-side code. + +### Developer Experience + +- Never expose deployment tokens or environment secrets. +- Validate deployment targets before triggering. +- Require confirmation for production deployments. +- Never auto-deploy to production without review. + +### Launch + +- Never expose deployment tokens or environment secrets. +- Validate deployment targets before triggering. +- Require confirmation for production deployments. +- Never auto-deploy to production without review. + +### Developer Hub + +- Never expose OAuth client secrets or app signing keys. +- Validate all app installation scopes. +- Never grant broader permissions than required. +- Keep app credentials server-side only. + +### Brand Kit + +- Never expose Brand Kit API tokens. +- Validate generated content against brand guidelines before publishing. +- Treat Knowledge Vault content as brand-governed source material. +- Confirm resource UIDs before any destructive operation. + +## The four safety pillars + +Every skill's Security section addresses four areas. + +### 1. Defaults + +The standing rules the skill always applies, for example, "delivery tokens are client-safe; management tokens are not," or "never recommend enabling Live Preview in production builds." + +### 2. Destructive actions + +Most skills are **advisory and read-only**: they explain and generate code but never mutate your stack. They explicitly refuse to delete, publish, unpublish, or overwrite, and will explain the impact instead. + +**Action skills** can cause external side effects and gate them behind explicit confirmation: + +- **Trigger & Monitor Launch Deployments**. Requires explicit confirmation for production deployments; never auto-deploys; exits non-zero on failure. +- **Sync Launch env vars**. Treats any PATCH as a destructive external action; confirms the target project/environment; prefers dry-run. +- **Migration Companion**. Gates login, stack creation, and code edits behind confirmation. + +### 3. Secrets + +No skill ever prints, echoes, infers, or stores secrets. If you paste a token, the skill acknowledges it at a high level and does not repeat it. Examples always use placeholders and environment variables. The Launch skills log only key names and counts, never values. + +### 4. Environment variables + +Credentials belong in environment variables, never in source or client-visible config. Skills use descriptive placeholders such as `CONTENTSTACK_API_KEY`, `CONTENTSTACK_DELIVERY_TOKEN`, and `CONTENTSTACK_MANAGEMENT_TOKEN`, and recommend server-side injection for privileged credentials. + +## Token safety quick reference + +A recurring theme across CMS skills: + +| Token | Client-safe? | Use | +| --- | --- | --- | +| **Delivery token** | Yes | Read published content via the CDA | +| **Preview token** | Treat as sensitive | Read unpublished draft content for Live Preview | +| **Management token** | No, server-side only | Stack-level read/write (CMA) | +| **Authtoken / OAuth** | No, server-side only | User sessions and automation (OAuth preferred in SSO orgs) | + +See [Tokens & Authentication](../skills/cms-tokens-authentication.md) for full guidance. + +## What this means for you + +- You can ask advisory skills anything. They won't change your stack. +- Action skills will pause and ask before doing anything irreversible or production-facing. +- The agent won't hardcode your credentials, even if you ask it to. It will use environment variables instead. (You can confirm this with the test in [Verify your setup](../get-started/verify-setup.md).) diff --git a/docs/how-it-works/skill-anatomy.md b/docs/how-it-works/skill-anatomy.md new file mode 100644 index 0000000..c2ff9c9 --- /dev/null +++ b/docs/how-it-works/skill-anatomy.md @@ -0,0 +1,89 @@ +--- +title: Anatomy of a SKILL.md +description: The structure every Contentstack skill follows, section by section. +--- + +# Anatomy of a SKILL.md + +Every skill is a single `SKILL.md` file at `skills//SKILL.md`. Skills share a consistent structure so agents can parse them reliably and authors can write them predictably. + +## Frontmatter + +YAML at the top of the file configures how the skill is loaded: + +```yaml +--- +name: dx-delivery-sdk +description: "Help agents write correct, production-ready TypeScript using @contentstack/delivery-sdk…" +allowed-tools: Read Grep Glob +--- +``` + +Common keys: + +| Key | Purpose | +| --- | --- | +| `name` | The skill's display name / identifier. | +| `description` | One-paragraph summary used for routing and discovery. | +| `allowed-tools` | Restricts which tools the agent may use (most advisory skills are `Read Grep Glob`: read-only). | +| `argument-hint` | Hints expected arguments for action skills (e.g. `[project_uid] [environment_uid]`). | +| `disable-model-invocation` | Marks a skill that should only run when explicitly invoked, not auto-routed (used by the Launch action skills). | +| `context` / `agent` | Execution hints (e.g. `context: fork`, `agent: general-purpose` or `agent: plan`). | + +When generated for Codex, frontmatter is stripped: the body becomes the instructions. + +## Body sections + +The Markdown body follows a repeatable outline. Not every skill uses every section, but most include: + +| Section | What it captures | +| --- | --- | +| **Description** | What the skill does. | +| **When to Use** | The routing trigger: the user intents that should activate it. | +| **User Problem** | The underlying need the skill addresses. | +| **Success Criteria** | What a correct answer looks like. | +| **Expected Inputs** | What the agent should gather (UIDs, locale, framework, etc.). | +| **Expected Outputs** | The deliverables (code, recommendations, checklists). | +| **Example User Requests** | Representative prompts the skill handles. | +| **Workflow Summary** | The step-by-step approach. | +| **Instructions** | The detailed rules and decision logic: the core of the skill. | +| **Output Format** | How answers should be shaped. | +| **Tooling Notes** | Which tools/SDKs to prefer; read-only vs action behavior. | +| **Security** | Defaults, destructive-action gating, secret handling, env vars. | +| **Product Context** | The product area and its shared safety rules. | +| **References** | Bundled `references/` files to read on demand. | +| **Examples** | Few-shot user/assistant pairs that calibrate behavior. | + +## Instructions: two styles + +The **Instructions** section appears in two forms across the bundle: + +- **Prose with subheadings**: narrative rules grouped under headings (e.g. Delivery SDK, Webhooks). +- **Structured JSON blocks**: an array of `{ "heading", "content" }` objects (e.g. Assets, Branches & Aliases, Environments & Publishing, Localization). These render as discrete rule cards. + +Both are valid; they encode the same kind of guidance. + +## References + +When a skill needs authoritative detail beyond the body, it ships `references/` files and points to them: + +``` +### [Delivery SDK Spec](references/delivery-sdk-spec.md) (product doc, required) +- Source: Official Docs (…) +- Summary: … +- Read: references/delivery-sdk-spec.md +``` + +The agent reads these **on demand**, only when the task actually needs them: to keep context lean. + +## Examples (few-shot) + +Many skills end with worked **User → Assistant** pairs, often tagged `few shot` or `edge case`. These calibrate tone, format, and especially safety responses (for instance, how to refuse hardcoding a token, or how to gate a destructive action). + +## Why the consistency matters + +A predictable structure means: + +- Agents can find the routing trigger, the rules, and the guardrails in the same place every time. +- Documentation pages map almost 1:1 to skill sections, so the [skills reference](../skills/index.md) can be generated from source. +- Authors have a template to follow. See [Authoring conventions](../contributing/authoring-conventions.md). diff --git a/docs/overview/concepts.md b/docs/overview/concepts.md new file mode 100644 index 0000000..76240b3 --- /dev/null +++ b/docs/overview/concepts.md @@ -0,0 +1,64 @@ +--- +title: Concepts & terminology +description: The core building blocks of Contentstack Agent Skills, skills, the router, references, bundled scripts, and generated trees. +--- + +# Concepts & terminology + +This page defines the vocabulary used throughout the documentation. + +## Skill + +A **skill** is a single Contentstack capability packaged as instructions for an AI agent. Each skill lives at `skills//SKILL.md` and describes one focused area, for example, querying entries or designing a content model. A skill tells the agent *when* it applies, *what* good output looks like, *how* to produce it, and *which* safety rules to enforce. + +See [Anatomy of a SKILL.md](../how-it-works/skill-anatomy.md) for the full structure. + +## Slug + +The **slug** is a skill's directory name and stable identifier, for example `cms-entries` or `dx-delivery-sdk`. Slugs are used in the `skills` CLI, in the manifest, and as the page names in the [skills reference](../skills/index.md). + +## Router + +The **router** is the entry point that maps a user request to the right skill. It's a table of "when the user asks… → use this skill" rows. Your agent loads the router into context and uses it to decide which skill to apply. + +- Canonical source: `skills/CLAUDE.md` +- Cursor form: `cursor/rules/00-router.mdc` (marked `alwaysApply: true`) +- Codex form: `codex/AGENTS.md` + +See [The router](../how-it-works/router.md) for details. + +## References + +Some skills ship extra **reference material** in a `references/` folder next to the skill, for example the Delivery SDK spec or the Brand Kit API reference. The agent reads these on demand only when the task needs them, rather than loading everything up front. Reference-backed skills include `dx-delivery-sdk`, `brand-kit-assistant`, `developer-hub-app-architect`, and `migration-companion`. + +## Bundled scripts + +A few skills ship executable **scripts** in a `scripts/` folder. The Migration Companion, for example, bundles prerequisite checkers and post-migration evaluation scripts. The agent invokes these by absolute path during a workflow. + +## Source of truth vs generated trees + +`skills/` is the **source of truth**: the only place you edit. Every other tool-specific tree is **generated** from it: + +``` +skills//SKILL.md ──► cursor/rules/NN-.mdc + ──► codex//SKILL.md +skills/CLAUDE.md (router) ──► cursor/rules/00-router.mdc + ──► codex/AGENTS.md +``` + +The `cursor/rules/` and `codex/` directories are build artifacts. Never edit them by hand. They're regenerated by build scripts and a GitHub Action will fail any pull request whose generated trees have drifted. See [Architecture](../how-it-works/architecture.md). + +## Manifest + +`manifest.json` lists every skill with its `slug`, `title`, and `product`. It's a machine-readable index of the bundle and a convenient input when generating documentation or tooling. + +## Product + +Each skill is tagged with a **product** area: `CMS`, `Developer Experience`, `Launch`, `Brand Kit`, or `Developer Hub`. Products carry shared safety defaults, for example, every CMS skill enforces "never expose management tokens" and "route CMA calls through a server-side proxy." + +## Advisory vs action skills + +- **Advisory skills** (the majority) are read-only. They explain, design, review, and generate code but never mutate your Contentstack stack. Examples: Entries, Data Modeling, Webhooks. +- **Action skills** can perform external operations and therefore gate them behind confirmation. Examples: the Launch deployment skills (trigger a deploy, patch environment variables) and the Migration Companion (creates a stack, edits your repo). + +The distinction matters for trust. See the [Security & safety model](../how-it-works/security-model.md). diff --git a/docs/overview/introduction.md b/docs/overview/introduction.md new file mode 100644 index 0000000..246a594 --- /dev/null +++ b/docs/overview/introduction.md @@ -0,0 +1,55 @@ +--- +title: Introduction +description: What Contentstack Agent Skills are, the problem they solve, and how the bundle is structured. +--- + +# Introduction + +## What are agent skills? + +An **agent skill** is a self-contained instruction set that teaches an AI coding assistant how to perform a specific task correctly. Each skill captures Contentstack's recommended approach to one area: data modeling, entry queries, asset delivery, Live Preview, Launch deployments, and so on, including the patterns to follow, the mistakes to avoid, and the safety rules to enforce. + +Contentstack Agent Skills bundle **22 of these skills** into a single package you can install into the AI tool you already use. Once installed, your assistant automatically reaches for the right skill based on what you ask. You don't have to remember which file to open or paste documentation into your prompt. + +## The problem they solve + +AI coding assistants are capable but generic. Out of the box they tend to: + +- Use outdated or invented SDK method names and chain orders. +- Mix up the Content Delivery API (CDA) and Content Management API (CMA). +- Suggest unsafe patterns: hardcoded tokens, management tokens in client code, reused Live Preview stacks. +- Over-model content, create deep reference chains, or miss localization and governance constraints. + +Agent skills close that gap. They give the assistant Contentstack-specific knowledge and guardrails so its output is correct, production-ready, and safe by default. + +## What's in the bundle + +The 22 skills span five Contentstack product areas: + +| Product | Skills | +| --- | --- | +| **CMS** | Assets · Branches & Aliases · Data Modeling · Entries · Environments & Publishing · Localization · Releases · Roles & Permissions · Taxonomy · Tokens & Authentication · Variants & Personalization · Webhooks · Workflows | +| **Developer Experience** | Delivery SDK · Contentstack Kickstart Next · Migrate JS→TS SDK · Live Preview & Visual Builder Support · Migration Companion | +| **Launch** | Sync env vars from `.env.example` · Trigger & Monitor Deployments | +| **Brand Kit** | Brand Kit Assistant | +| **Developer Hub** | Developer Hub App Architect | + +See the full [skills reference](../skills/index.md) for a description of each. + +## One source, five formats + +Every skill is authored once as a `SKILL.md` file and packaged for five tools: + +- **Claude Code**: installable plugin +- **Cursor**: rule files (`.mdc`) +- **Codex / OpenAI agents**: a markdown tree +- **Gemini CLI**: an extension manifest +- **[`skills` CLI](https://github.com/anthropics/skills)**: pulls any single skill on demand + +You install only one. The bundle lives at [github.com/contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills). The [supported tools](supported-tools.md) page explains what each format produces, and [how skills work](../how-it-works/architecture.md) explains how the formats stay in sync. + +## Next steps + +- New here? Start with the [Quickstart](../get-started/quickstart.md). +- Want the mental model first? Read [Concepts & terminology](concepts.md). +- Curious what's covered? Browse the [skills reference](../skills/index.md). diff --git a/docs/overview/supported-tools.md b/docs/overview/supported-tools.md new file mode 100644 index 0000000..2673d96 --- /dev/null +++ b/docs/overview/supported-tools.md @@ -0,0 +1,37 @@ +--- +title: Supported tools & compatibility +description: The five formats Contentstack Agent Skills ship in, what each install produces, and how to choose. +--- + +# Supported tools & compatibility + +The same 22 skills are packaged in five formats. You only need to install one: pick the row that matches your assistant. + +| Tool | What you install | What it produces | Install guide | +| ------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| **Claude Code** | A plugin from the marketplace | The router is loaded into context; Claude auto-selects the matching skill | [Install for Claude Code](../get-started/install-claude-code.md) | +| **Cursor** | The plugin, or `cursor/rules/*.mdc` copied into `.cursor/rules/` | An always-on router rule plus one rule per skill | [Install for Cursor](../get-started/install-cursor.md) | +| **Codex / OpenAI agents** | The `codex/` markdown tree | `codex/AGENTS.md` router plus `codex//SKILL.md` per skill | [Install for Codex](../get-started/install-codex.md) | +| **Gemini CLI** | The extension via `gemini extensions install contentstack/contentstack-agent-skills` | The extension manifest wires the skills into Gemini | [Install for Gemini](../get-started/install-gemini.md) | +| **`skills` CLI** | A single skill on demand | Just the one skill you name | [Use the skills CLI](../get-started/skills-cli.md) | + +## How to choose + +- **You use one assistant for everything** → install the bundle for that tool (Claude Code, Cursor, Codex, or Gemini). The router ships with it, so the agent picks skills automatically. +- **You only want one capability** (e.g. just the Delivery SDK skill) → use the [`skills` CLI](../get-started/skills-cli.md) to pull that single skill. +- **Your team standardizes on a repo** → vendor the relevant tree (`cursor/rules/` or `codex/`) into your project so every contributor gets the same behavior. + +## What "auto-selection" means + +For the four full-bundle formats, the **router** is included and loaded into the agent's context. When you make a request, the agent reads the routing table, matches your intent to a skill, then loads and follows that skill. You don't name skills explicitly, though you can, if you want to force a specific one. + +The `skills` CLI is different: it installs exactly the skill you name and nothing else, so there's no router and no auto-selection. + +## Requirements + +- An AI coding assistant from the list above. +- For the Launch skills: Launch API access for the target project and environment. + +## Keeping skills current + +Because all formats are generated from a single source, every tool gets the same behavior and the same updates. When the bundle is updated, re-running your tool's install (or pulling the latest repo) brings the generated trees up to date. See [Architecture](../how-it-works/architecture.md) for how the trees are kept in sync. diff --git a/docs/skills/brand-kit-assistant.md b/docs/skills/brand-kit-assistant.md new file mode 100644 index 0000000..abc73e0 --- /dev/null +++ b/docs/skills/brand-kit-assistant.md @@ -0,0 +1,42 @@ +--- +title: Brand Kit Assistant +description: The entry point for Contentstack Brand Kit, concepts, setup, governance, Voice Profiles, Knowledge Vault, on-brand AI generation, and API-task routing. +--- + +# Brand Kit Assistant + +**Slug:** `brand-kit-assistant` · **Product:** Brand Kit · **Type:** Advisory + API routing · **Ships references** + +The primary entry point for Contentstack Brand Kit. It explains how Brand Kit, Voice Profiles, and Knowledge Vault fit together, guides setup and governance, routes API-specific tasks to the right capability, and enforces brand and safety rules before presenting anything as ready. + +## When it triggers + +When you ask about Brand Kit, Voice Profiles, Knowledge Vault, brand voice, tone, style rules, on-brand AI generation, setup, governance, or API usage. + +## What it covers + +- **Concepts**: a Brand Kit container, one or more Voice Profiles (how content should sound), and a Knowledge Vault (brand facts and source material) used to ground AI generation. +- **Setup**: creating a Brand Kit from a website or file upload, and mapping content to a Voice Profile vs Knowledge Vault. +- **On-brand generation**: use a Voice Profile for tone/style plus Knowledge Vault for factual grounding, then validate output against brand guidelines before publishing. +- **Knowledge Vault behavior**: it's vector-based semantic storage. It does **not** return original files or PDFs; keep source documents in your DAM/document system. +- **API guidance**: Brand Kit Management API (Brand Kits, Voice Profiles), Knowledge Vault API (ingest, update, delete, search, chunk retrieval), Generative AI API (content generation). Respects the 10 req/s per-organization rate limit and region-specific base URLs. + +## References + +Ships scoped API references: `references/brand-kit-management-api-reference.md` and `references/knowledge-vault-api-reference-skill.md`, read on demand for specific operations. + +## Example prompts + +- "What is Contentstack Brand Kit and what can I use it for?" +- "How do I create a Brand Kit from our website?" +- "Update this Voice Profile to match our brand voice." +- "How do I make AI-generated content stay on-brand?" +- "Can I get the original files back from Knowledge Vault?" + +## Safety notes + +Never exposes Brand Kit API tokens, authtokens, or decrypted credentials. Acknowledges secrets at a high level without echoing them. Requires explicit confirmation and a confirmed UID before destructive actions (delete, unpublish, overwrite). Validates generated content against brand guidelines before calling it ready and won't override brand rules without approval. Asks for missing identifiers, auth, region, or source content rather than guessing. + +## Related + +- [Tokens & Authentication](cms-tokens-authentication.md) · [Security & safety model](../how-it-works/security-model.md) diff --git a/docs/skills/cms-assets.md b/docs/skills/cms-assets.md new file mode 100644 index 0000000..0d0fb70 --- /dev/null +++ b/docs/skills/cms-assets.md @@ -0,0 +1,38 @@ +--- +title: Assets +description: Organize, deliver, and transform assets in Contentstack: folders, Image Delivery API, publishing lifecycle, CDN behavior, and limits. +--- + +# Assets + +**Slug:** `cms-assets` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises developers on organizing, delivering, and transforming assets in Contentstack: folder structure, Image Delivery API transformations, publishing lifecycle, CDN behavior, and common limits. + +## When it triggers + +When you ask about uploading, organizing, delivering, transforming, publishing, or troubleshooting images and other media files in Contentstack. + +## What it covers + +- **Folder organization**: clear structures like `/images/heroes`, `/images/products`, `/documents/legal`. Moving assets between folders preserves UIDs and references. +- **Image Delivery API**: `images.contentstack.io` with on-the-fly transforms via URL params (`width`, `height`, `quality`, `format`, `crop`, `trim`, `orient`, `overlay`, `pad`, `fit`, `dpr`). Chain multiple transforms in one URL; prefer WebP for modern browsers. Non-image assets serve from `assets.contentstack.io`. +- **Publishing lifecycle**: assets publish independently of entries. An asset must be published to an environment before referenced entries display it live. Unpublishing removes it from delivery but doesn't delete the file. +- **Replacing vs deleting**: replacing creates a new version but keeps the same UID and references; deleting breaks all references. Check references before deleting. +- **Key limits**: max file size 700 MB (UI) / 100 MB (API); max 10 assets per batch upload; default 10,000 assets per stack and 500,000 per organization; filenames can't change after upload. Image Delivery transforms don't apply to images inserted directly into Rich Text Editor fields. + +## Example prompts + +- "How do I serve responsive images from Contentstack?" +- "What image transformations does Contentstack support?" +- "How should I organize my assets into folders?" +- "Does deleting an asset break references in entries?" +- "What is the maximum file size I can upload?" + +## Safety notes + +Read-only advisory. Never uploads, deletes, publishes, or modifies assets. Delivery tokens and asset URLs are client-safe; never expose management tokens or API keys. Use environment variables for credentials in examples. + +## Related + +- [Environments & Publishing](cms-environments-publishing.md) · [Entries](cms-entries.md) · [Data Modeling Best Practices](cms-data-modeling-best-practices.md) diff --git a/docs/skills/cms-branches-aliases.md b/docs/skills/cms-branches-aliases.md new file mode 100644 index 0000000..ae6d83f --- /dev/null +++ b/docs/skills/cms-branches-aliases.md @@ -0,0 +1,39 @@ +--- +title: Branches & Aliases +description: Use Contentstack branches for isolated content development and aliases for zero-downtime deployments, with CI/CD, merge, and rollback patterns. +--- + +# Branches & Aliases + +**Slug:** `cms-branches-aliases` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on using branches for isolated content/schema development and aliases for zero-downtime deployments: branch strategy, branch-specific vs global modules, CI/CD integration, merge behavior, and rollback. + +## When it triggers + +When you ask about branches, aliases, CI/CD integration with Contentstack, deployment strategies, or branch-specific vs global module behavior. + +## What it covers + +- **Branch basics**: branches copy the source branch's content types, global fields, entries, and assets into an isolated workspace. Max 5 branches per stack; one create/delete at a time across an org; only owners, admins, and developers can manage them. +- **Branch-specific vs global modules**: *branch-specific:* content types, global fields, entries, assets, publish queue, releases, languages, extensions, audit logs, labels, search. *Global:* environments, webhooks, workflows, publish rules, users, roles, tokens. +- **Alias-based deployment**: aliases point to branches. Hardcode an alias (e.g. `deploy`) in frontend code instead of a branch UID; switch production by reassigning the alias, and roll back by reassigning it back. Two aliases can point to one branch, but a branch and alias can't share a UID. +- **CI/CD pattern**: branch from main → change schema/content → test on staging → reassign the production alias → reassign back instantly if something breaks. +- **Branch strategy**: keep branches short-lived; prefer trunk-based workflow. Don't use branches as permanent environments (use environments for that). +- **SDK initialization**: pass the branch or alias ID explicitly (e.g. `branch: 'deploy'`); without a branch header, `main` is the default. Always pass it explicitly in scripts. + +## Example prompts + +- "How do I use branches for content schema development?" +- "What's the difference between branch-specific and global modules?" +- "How do I deploy content changes with zero downtime?" +- "How do branches work with my CI/CD pipeline?" +- "Can I roll back a bad deployment?" + +## Safety notes + +Read-only advisory: does not create, delete, merge, or reassign branches or aliases. Use environment variables for credentials; keep guidance compatible with branch- and alias-scoped credentials. + +## Related + +- [Releases](cms-releases.md) · [Environments & Publishing](cms-environments-publishing.md) · [Roles & Permissions](cms-roles-permissions.md) diff --git a/docs/skills/cms-data-modeling-best-practices.md b/docs/skills/cms-data-modeling-best-practices.md new file mode 100644 index 0000000..59bb84e --- /dev/null +++ b/docs/skills/cms-data-modeling-best-practices.md @@ -0,0 +1,52 @@ +--- +title: Data Modeling Best Practices +description: Model Contentstack content with the simplest reusable structure: when to use content types, references, global fields, groups, modular blocks, JSON RTE, taxonomy, and tags. +--- + +# Data Modeling Best Practices + +**Slug:** `cms-data-modeling-best-practices` · **Product:** CMS · **Type:** Advisory (read-only) + +Guides developers to model content using the simplest reusable structure and avoid over-modeling, deep reference chains, and channel-specific schema sprawl. + +## When it triggers + +When designing, reviewing, or refactoring content models before creating or changing schemas. + +## What it covers + +The skill applies fast decision rules to pick the simplest construct that fits: + +| Use… | When… | +| --- | --- | +| **Content type** | A real domain concept with its own lifecycle. | +| **Reference** | Reusable content with independent ownership. | +| **Global field** | The same nested field set across multiple content types. | +| **Group** | Parent-owned nested data inside one content type. | +| **Modular blocks** | Page-local composition. | +| **JSON RTE** | Narrative content. | +| **Taxonomy** | Governed classification. | +| **Tags** | Lightweight internal labels. | + +Core principles: + +- Prefer reuse only when content changes independently or appears across entries; keep parent-owned data inline. +- Treat content types as API contracts: avoid deep reference chains, oversized modular blocks, and hiding filterable facts inside rich text. +- Localize only fields that need translation; keep names clear; avoid channel-specific schema pollution. +- Explain tradeoffs and include migration cautions when schema changes are implied. + +## Example prompts + +- "How should I model a landing page with reusable sections?" +- "Should this data be a global field, group, or content type?" +- "Review this content model and tell me what to simplify." +- "What's the best way to handle localization for shared content?" +- "How do I model product categories for filtering and reuse?" + +## Safety notes + +Read-only advisory. Never performs schema changes, publishing, or destructive actions. Uses placeholders and environment variables for any example credentials. + +## Related + +- [Taxonomy](cms-taxonomy.md) · [Localization](cms-localization.md) · [Entries](cms-entries.md) diff --git a/docs/skills/cms-entries.md b/docs/skills/cms-entries.md new file mode 100644 index 0000000..cf81b64 --- /dev/null +++ b/docs/skills/cms-entries.md @@ -0,0 +1,41 @@ +--- +title: Entries +description: Query, localize, version, publish, and structure Contentstack entries for efficient delivery: CDA usage, reference expansion, pagination, bulk ops, and the Sync API. +--- + +# Entries + +**Slug:** `cms-entries` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on querying, localizing, versioning, publishing, and structuring entries for efficient delivery, with a focus on CDA usage, reference expansion, pagination, bulk operations, and Sync API patterns. + +## When it triggers + +When you ask about fetching entries, building CDA queries, handling localization, publishing workflows, versioning behavior, bulk operations, or entry-related performance issues. + +## What it covers + +- **CDA vs CMA**: states up front whether guidance applies to the Content Delivery API (frontend reads) or the Content Management API (authoring). A key guardrail: never use the CMA for frontend reads. +- **Query syntax**: correct operators and response shapes, including filtering by fields inside Modular Blocks. +- **Reference expansion**: including referenced entries in a CDA response. +- **Pagination & performance**: paging through all entries of a content type efficiently. +- **Versioning & publishing**: how versioning works, and the difference between saving and publishing. +- **Localization**: locale-aware entry behavior. + +For SDK code specifically, this pairs with the [Delivery SDK](dx-delivery-sdk.md) skill. + +## Example prompts + +- "How do I query entries filtered by a field inside Modular Blocks?" +- "How does entry versioning work in Contentstack?" +- "What's the difference between publishing and saving?" +- "How do I include referenced entries in my CDA response?" +- "How do I paginate through all entries of a content type?" + +## Safety notes + +Read-only advisory. Never creates, updates, publishes, or deletes entries. Delivery tokens are client-safe; management tokens are not. Use environment variables for credentials in examples. + +## Related + +- [Delivery SDK](dx-delivery-sdk.md) · [Localization](cms-localization.md) · [Environments & Publishing](cms-environments-publishing.md) diff --git a/docs/skills/cms-environments-publishing.md b/docs/skills/cms-environments-publishing.md new file mode 100644 index 0000000..c846495 --- /dev/null +++ b/docs/skills/cms-environments-publishing.md @@ -0,0 +1,40 @@ +--- +title: Environments & Publishing +description: Configure environments, publish content, use delivery and preview tokens, leverage the Sync API, and understand CDN and publish-queue behavior in Contentstack. +--- + +# Environments & Publishing + +**Slug:** `cms-environments-publishing` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on configuring environments, publishing content, using delivery and preview tokens, leveraging the Sync API, and understanding CDN and publish-queue behavior. + +## When it triggers + +When you ask about environment setup, publishing behavior, delivery or preview tokens, the Sync API, scheduling, or CDN and caching configuration. + +## What it covers + +- **Environment design**: treat environments as deployment targets (development, staging, production). Default max 5 per stack. Environments are global modules, shared across branches. +- **Publishing fundamentals**: content is a draft until published to an environment; publishing can target multiple environments and locales. Use `api_version: 3.2` for nested reference publishing so the full reference tree resolves automatically. Always publish entries with their references. +- **Token types**: *Delivery Token:* published content via the CDA, environment-scoped, client-safe. *Preview Token:* unpublished draft content for Live Preview. *Management Token:* stack-level read/write, server-side only. +- **SDK initialization**: stack API key + delivery token + environment, optionally branch/alias. CDA base URLs are region-specific (`cdn.contentstack.io` for AWS NA, `eu-cdn.contentstack.com` for AWS EU, `au-cdn.contentstack.com` for AWS AU). +- **Sync API**: recommended for static sites, offline apps, or local caches. First request returns all published content plus a `sync_token`; later requests return only changes. Prefer it over polling. +- **Publish queue**: tracks publish/unpublish status; each branch has its own queue; scheduled publishes can be cancelled before execution. +- **Rate limits**: 10 req/s individual, 1 req/s bulk per org. Use exponential backoff with jitter; the CLI bulk publish plugin handles rate limiting automatically. + +## Example prompts + +- "How many environments should I set up?" +- "What's the difference between a delivery token and a preview token?" +- "My content isn't showing on the live site after publishing." +- "How does the Sync API work?" +- "Can I schedule content to publish at a future time?" + +## Safety notes + +Read-only advisory. Never publishes, unpublishes, or modifies environments. Delivery tokens are client-safe; management tokens must never be exposed client-side. Use environment variables for all token examples. + +## Related + +- [Tokens & Authentication](cms-tokens-authentication.md) · [Releases](cms-releases.md) · [Entries](cms-entries.md) · [Branches & Aliases](cms-branches-aliases.md) diff --git a/docs/skills/cms-live-preview-visual-builder-support-assistant.md b/docs/skills/cms-live-preview-visual-builder-support-assistant.md new file mode 100644 index 0000000..e14c1b2 --- /dev/null +++ b/docs/skills/cms-live-preview-visual-builder-support-assistant.md @@ -0,0 +1,45 @@ +--- +title: Live Preview & Visual Builder Support +description: Diagnose and implement Contentstack Live Preview and Visual Builder across CSR, SSR, SSG, middleware/BFF, and tagging flows. +--- + +# Live Preview & Visual Builder Support + +**Slug:** `cms-live-preview-visual-builder-support-assistant` · **Product:** Developer Experience · **Type:** Advisory (read-only) + +Diagnoses and guides Live Preview and Visual Builder implementations: it traces preview context, identifies the broken contract, and recommends the smallest correct fix. It works as a code reviewer when repo access is available, and as an implementation guide when it isn't. + +## When it triggers + +When implementing or debugging Live Preview or Visual Builder: blank preview panels, stale or published-only preview, lost preview context after navigation, shared SSR state, cache contamination, or edit-tag mapping failures. + +## How it works + +The skill classifies a symptom into a failure bucket, identifies the rendering strategy (CSR / SSR / SSG / middleware-BFF), asks only the minimum evidence-based questions, traces the preview contract, names the most likely broken link, then recommends the smallest fix plus a short verification checklist. + +### Symptom buckets + +| Symptom | Likely broken contract | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| Blank preview / setup status error | Page can't initialize a valid preview session (URL embeddable? `X-Frame-Options`? SDK `init()` on the route?) | +| Published content in preview | Preview context exists in browser but never reaches the content fetch (missing hash, wrong host, no preview token) | +| Edits don't update (CSR) | `ssr: false`? `onEntryChange()` / `onLiveEdit()` registered and refetching? | +| Preview breaks after navigation | Hash propagation: links/redirects strip `live_preview`, `content_type_uid`, `entry_uid`, `locale` | +| Wrong entry / another editor's draft (SSR) | Request-scoped state being shared or cached; use request-scoped clients, disable caching when `live_preview` is present | +| Visual Builder clicks open wrong field | Tagging: `mode: "builder"`, `addEditableTags()` in the data layer, `$` props spread onto real DOM nodes, correct block indices | + +## Example prompts + +- "Why is Live Preview not updating when I edit content?" +- "How do I set up Live Preview for SSR?" +- "What's the difference between `ssr: true` and `ssr: false`?" +- "My preview iframe is blank. What should I check?" +- "How do preview tokens and live preview hashes work?" + +## Safety notes + +Never makes changes automatically. Provides safe diagnostics and requires confirmation before any config change. Treats preview tokens and live preview hashes as sensitive; never asks for tokens, cookies, or auth headers; never recommends enabling Live Preview in production builds. If a secret appears in input, advises rotating it. + +## Related + +- [Delivery SDK](dx-delivery-sdk.md) · [Environments & Publishing](cms-environments-publishing.md) · [Entries](cms-entries.md) diff --git a/docs/skills/cms-localization.md b/docs/skills/cms-localization.md new file mode 100644 index 0000000..2db9f18 --- /dev/null +++ b/docs/skills/cms-localization.md @@ -0,0 +1,39 @@ +--- +title: Localization +description: Design multilingual delivery in Contentstack: language setup, fallback chains, localized vs unlocalized entries, non-localizable fields, and multi-locale publishing. +--- + +# Localization + +**Slug:** `cms-localization` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on Contentstack localization with correct fallback behavior, efficient editorial workflows, and minimal redundancy. The skill distinguishes CMS editorial behavior from CDA delivery behavior, and clarifies which you mean before answering. + +## When it triggers + +When you ask about languages, fallback chains, localizing entries, non-localizable fields, or multi-locale publishing. + +## What it covers + +- **Master language**: permanent, set at stack creation, and ends every fallback chain. +- **Fallback chain design**: each language can have one fallback; inheritance is a chain (e.g. `fr-ca → fr-fr → en-us`). Changing fallback relationships later affects existing content inheritance. +- **Localized vs unlocalized entries**: a localized entry is an independent copy with its own version history, publishing status, and workflow state; an unlocalized entry inherits from its fallback chain. Localizing is one-way per locale and entry. +- **Non-localizable fields**: mark structural/shared data non-localizable (SKUs, prices, dates, coordinates, boolean flags, shared assets, identifiers); keep human-readable text localizable. +- **CDA locale queries**: pass `locale` explicitly; use `include_fallback=true` to apply the full fallback chain (without it, only the exact locale is checked). +- **Multi-locale publishing**: editors can publish multiple locale versions from the master-language entry (subject to plan limits). Only the latest version of each localized entry is published; localized versions can be deleted only from the master entry's delete modal. + +## Example prompts + +- "How do I set up languages with fallback in Contentstack?" +- "What's the difference between a localized and unlocalized entry?" +- "Which fields should I mark as non-localizable?" +- "How do I publish content in multiple languages at once?" +- "What happens if a locale has no content?" + +## Safety notes + +Read-only advisory. Requires explicit confirmation before any destructive action and never auto-executes delete/overwrite/publish. Use environment variables for all credentials. + +## Related + +- [Entries](cms-entries.md) · [Data Modeling Best Practices](cms-data-modeling-best-practices.md) · [Taxonomy](cms-taxonomy.md) diff --git a/docs/skills/cms-releases.md b/docs/skills/cms-releases.md new file mode 100644 index 0000000..109cdbc --- /dev/null +++ b/docs/skills/cms-releases.md @@ -0,0 +1,38 @@ +--- +title: Releases +description: Use Contentstack Releases for coordinated, atomic content deployment: creation, item management, staged deployment, webhook-storm prevention, and CI/CD. +--- + +# Releases + +**Slug:** `cms-releases` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on using Releases to deploy related content changes atomically so campaigns, redesigns, or coordinated updates go live together without manual coordination errors. + +## When it triggers + +When you ask about deploying multiple content changes together, campaign launches, coordinated content updates, release scheduling, or CI/CD content deployment. + +## What it covers + +- **Release workflow**: create a release with a descriptive name, add all related entries and assets (across content types and locales), deploy to staging first, validate, then deploy to production. Specify which version of each entry to deploy when needed. +- **Webhook storm**: a release deployment triggers one webhook event per item. Debounce receivers and inspect the `source` key in payloads. See [Webhooks](cms-webhooks.md) for receiver handling. +- **Limitations**: max 100 items per API call when adding items; release titles max 50 characters; updating items to latest versions does not auto-add new references from updated entries; releases are branch-specific. +- **CI/CD integration**: create a release → add changed items → deploy to staging → run tests → deploy to production on success. Combine with branches and aliases. +- **When not to use**: not for routine single-entry publishes; use releases when coordinated multi-item deployment is required. + +## Example prompts + +- "How do I deploy a campaign with 50 entries at once?" +- "Can I schedule a release for a future date?" +- "My static site rebuilds hundreds of times per release deployment." +- "How do I integrate releases with my CI/CD pipeline?" +- "What are the limits on releases?" + +## Safety notes + +Read-only advisory. Never creates, deploys, updates, or deletes releases. Use environment variables for credentials; no client-side access to management credentials. + +## Related + +- [Webhooks](cms-webhooks.md) · [Branches & Aliases](cms-branches-aliases.md) · [Environments & Publishing](cms-environments-publishing.md) diff --git a/docs/skills/cms-roles-permissions.md b/docs/skills/cms-roles-permissions.md new file mode 100644 index 0000000..45f94e7 --- /dev/null +++ b/docs/skills/cms-roles-permissions.md @@ -0,0 +1,39 @@ +--- +title: Roles & Permissions +description: Design roles, permissions, teams, and token access in Contentstack with least-privilege guidance. +--- + +# Roles & Permissions + +**Slug:** `cms-roles-permissions` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on designing roles, permissions, teams, and token access: built-in roles, custom roles, permission merging, team-based access, and token capabilities: with least-privilege guidance. + +## When it triggers + +When you ask about user permissions, role design, team management, token capabilities, access control, or automation access. + +## What it covers + +- **Built-in roles**: Owner, Admin, Developer, Content Manager. Use them when they fit; otherwise create a custom role. +- **Custom roles**: limit access by content type, environment, locale, branch, or action. Describe permissions by module, content type, and action; use `$all` for all instances when applicable. +- **Permission merging**: multiple roles combine allowed actions permissively, but explicit denials override grants. Watch overlap risks when roles are reused across teams/stacks. +- **Teams**: recommended for shared access across users and stacks; team membership maps users to stack roles and scales better than assigning roles individually. +- **Token capabilities**: choose the least-privileged token (management tokens, authtokens, OAuth) with SSO/org-owner edge cases noted. +- **Rate limits**: check `X-RateLimit-Remaining` and use backoff for automation/bulk operations. + +## Example prompts + +- "What built-in roles does Contentstack have?" +- "How do I restrict editors to only certain content types?" +- "What can management tokens do vs authtokens?" +- "How do I set up teams for multiple stacks?" +- "What happens when a user has multiple roles?" + +## Safety notes + +Read-only advisory. Never creates, modifies, or deletes roles, users, teams, or tokens. Never recommends management tokens in client-side code; prefers server-side proxies for privileged CMA access. Delivery tokens are client-safe for read-only delivery only. + +## Related + +- [Tokens & Authentication](cms-tokens-authentication.md) · [Workflows & Publish Rules](cms-workflows.md) · [Branches & Aliases](cms-branches-aliases.md) diff --git a/docs/skills/cms-taxonomy.md b/docs/skills/cms-taxonomy.md new file mode 100644 index 0000000..c81b1a0 --- /dev/null +++ b/docs/skills/cms-taxonomy.md @@ -0,0 +1,38 @@ +--- +title: Taxonomy +description: Use Contentstack Taxonomy for hierarchical content classification and delivery-side filtering: taxonomy vs tags/labels/references, hierarchy design, CDA operators, localization, import/export. +--- + +# Taxonomy + +**Slug:** `cms-taxonomy` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on using Taxonomy for structured, hierarchical classification and delivery-side filtering, and on when taxonomy is the right mechanism versus tags, labels, or references. + +## When it triggers + +When you need help classifying content, designing category hierarchies, choosing between taxonomy and other classification approaches, or querying entries by category on the delivery side. + +## What it covers + +- **Use taxonomy when**: you need structured, hierarchical classification queryable on the delivery side (product categories, geographic regions, content topics, document types). +- **Don't use taxonomy when**: for freeform labels (use tags), internal CMS organization (use labels), or rich category pages with their own model (use a Category content type with references). +- **Hierarchy design**: plan before creating; keep it practical (usually 3–4 levels). Terms are parent-child ordered. Moving a term with children is blocked unless the force flag is used. +- **CDA filtering operators**: `$taxonomy_exists` (any term), `$taxonomy_equal` (specific term), `$taxonomy_below` (a term and descendants), `$taxonomy_above` (ancestors). +- **Localization & import/export**: localization is plan-dependent; localized terms share the master term's UID. Import/export supports JSON and CSV; invalid CSV rows are skipped while valid rows process. + +## Example prompts + +- "Should I use taxonomy or tags for product categories?" +- "How do I query entries by taxonomy term on the CDA?" +- "How do I design a taxonomy hierarchy for my site?" +- "Can I localize taxonomy terms?" +- "Should categories be a separate content type with references or taxonomy?" + +## Safety notes + +Read-only advisory. Never creates, modifies, moves, deletes, or imports taxonomy data. Use environment variables for credentials in examples. + +## Related + +- [Data Modeling Best Practices](cms-data-modeling-best-practices.md) · [Entries](cms-entries.md) · [Localization](cms-localization.md) diff --git a/docs/skills/cms-tokens-authentication.md b/docs/skills/cms-tokens-authentication.md new file mode 100644 index 0000000..5e96a3d --- /dev/null +++ b/docs/skills/cms-tokens-authentication.md @@ -0,0 +1,49 @@ +--- +title: Tokens & Authentication +description: Choose the right Contentstack authentication method and token type for frontend, backend, automation, and third-party apps: with security, rate-limit, and SSO guidance. +--- + +# Tokens & Authentication + +**Slug:** `cms-tokens-authentication` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on choosing the right authentication method and token type, with clear client-side vs server-side safety guidance, rate-limit awareness, and SSO considerations. + +## When it triggers + +When you ask about authentication, token types, API keys, rate limits, SSO integration, or credential security. + +## What it covers + +**Token decision rules:** + +| Use case | Token | +| --- | --- | +| Frontend reads of published content | Delivery token | +| Live Preview of draft content | Preview token | +| Backend automation, CI/CD, migration scripts | Management token | +| Interactive user sessions | Authtoken (only when appropriate) | +| Third-party apps | OAuth with scoped access | + +Plus: + +- **Key limits**: management tokens are stack-level and limited per stack; authtokens are user-specific with their own limits. Watch rate-limit headers and 429s. +- **SSO organizations**: SSO can restrict authtoken usage; for automation in SSO orgs, prefer management tokens or OAuth. +- **Security rules**. Never expose management tokens or authtokens client-side; use environment variables; rotate credentials; least privilege. +- **Rate-limit handling**: exponential backoff with jitter for 429s; check rate-limit headers before retrying. + +## Example prompts + +- "What token should I use in my frontend app?" +- "What's the difference between a management token and an authtoken?" +- "How do I handle rate limits in my script?" +- "Can I use authtokens in an SSO-enabled organization?" +- "How many management tokens can I have per stack?" + +## Safety notes + +Read-only advisory. Never creates, modifies, or deletes tokens. Never displays real secrets or example real tokens; always states whether a credential is client-safe or server-side only. Uses placeholders like `CONTENTSTACK_API_KEY`, `CONTENTSTACK_DELIVERY_TOKEN`, `CONTENTSTACK_MANAGEMENT_TOKEN`. + +## Related + +- [Roles & Permissions](cms-roles-permissions.md) · [Environments & Publishing](cms-environments-publishing.md) · [Security & safety model](../how-it-works/security-model.md) diff --git a/docs/skills/cms-variants-personalization.md b/docs/skills/cms-variants-personalization.md new file mode 100644 index 0000000..3023839 --- /dev/null +++ b/docs/skills/cms-variants-personalization.md @@ -0,0 +1,37 @@ +--- +title: Variants & Personalization +description: Use Contentstack Variants and Personalize for audience-targeted content: variants vs separate entries, variant groups, A/B testing, and Personalize integration. +--- + +# Variants & Personalization + +**Slug:** `cms-variants-personalization` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on delivering different content to different audiences without duplicating entire entries, and on integrating Personalize with the CMS. + +## When it triggers + +When you ask about content personalization, A/B testing, audience segmentation, variant creation, or integrating Personalize with the CMS. + +## What it covers + +- **Variants vs separate entries**: if ~80%+ of the content is shared and only headlines, images, or CTAs differ, use variants (lightweight overrides). If each audience needs a different page structure, references, and layout, use separate entries. Start with variants; split only when content diverges significantly. +- **Variant groups**: how variants are organized. +- **Personalize integration**: initialize the Contentstack SDK with stack credentials and the Personalize SDK with your project key. On each request, resolve the active experience from audience rules and pass the variant context when fetching entries. For SSR, use the Personalize Edge API to resolve variants at the CDN for best performance. +- **Start simple**: emphasizes maintainability; add complexity only when justified. + +## Example prompts + +- "How do I show different content to different user segments?" +- "Should I use variants or create separate entries per audience?" +- "How do I integrate Personalize with my frontend?" +- "What are variant groups?" +- "Can I A/B test content in Contentstack?" + +## Safety notes + +Read-only advisory. Never creates, modifies, or publishes variants. Use environment variables for credentials; never hardcode stack API keys or Personalize project keys. + +## Related + +- [Entries](cms-entries.md) · [Delivery SDK](dx-delivery-sdk.md) · [Data Modeling Best Practices](cms-data-modeling-best-practices.md) diff --git a/docs/skills/cms-webhooks.md b/docs/skills/cms-webhooks.md new file mode 100644 index 0000000..4216cd3 --- /dev/null +++ b/docs/skills/cms-webhooks.md @@ -0,0 +1,40 @@ +--- +title: Webhooks +description: Configure and consume Contentstack webhooks: event channels, payloads, signature verification, retries, release-triggered storms, and reliable receiver design. +--- + +# Webhooks + +**Slug:** `cms-webhooks` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on configuring and consuming webhooks for real-time event notifications, and on operational edge cases like duplicate deliveries, retries, release-triggered storms, and failed deliveries. + +## When it triggers + +When you need help setting up webhooks, choosing event channels, handling payloads, verifying signatures, debugging delivery issues, or integrating Contentstack with external systems (site rebuilds, search indexes, Slack, CI/CD). + +## What it covers + +- **Channels**: `{module}.{action}` form, e.g. `entries.create`, `entries.publish`, `assets.publish`, `content_types.update`, `entries.workflow_stage_change`. Start specific; use `$all` only when truly needed. +- **Payloads**: include module, `api_key`, event, `triggered_at`, data, and branch info. Use `concise_payload: true` when the receiver only needs identifiers. +- **Signature verification**: always validate the `X-Contentstack-Signature` header in production (HMAC-SHA256 over the raw body using the webhook secret). Reject missing/invalid signatures. +- **Release-webhook storm**: a release with many items can produce one event per item. Detect release-triggered events via the `source` key and debounce/batch so downstream systems trigger once per release. +- **Reliable receiver design**: validate signatures, return 2xx within 30 seconds, process asynchronously after acknowledgment, and handle duplicate deliveries idempotently. +- **Retry policies**: manual retries are logged for re-execution; auto retries use exponential backoff. Use execution logs for attempts, status codes, and response bodies. +- **Limits & scope**: max 100 webhooks per stack; webhooks are global but can be scoped to a branch; an org-level setting caps max connections per second. + +## Example prompts + +- "How do I trigger a site rebuild when content is published?" +- "How do I verify a webhook is genuinely from Contentstack?" +- "My webhook receiver gets hundreds of calls when I deploy a release." +- "What retry policy should I use?" +- "How do I debug missed webhook deliveries?" + +## Safety notes + +Read-only advisory. Never creates, updates, deletes, or sends webhooks. Always validate `X-Contentstack-Signature` in production; never echo raw secrets, tokens, or signatures; keep secrets in environment variables and verify server-side. + +## Related + +- [Releases](cms-releases.md) · [Workflows & Publish Rules](cms-workflows.md) · [Environments & Publishing](cms-environments-publishing.md) diff --git a/docs/skills/cms-workflows.md b/docs/skills/cms-workflows.md new file mode 100644 index 0000000..e9d57a7 --- /dev/null +++ b/docs/skills/cms-workflows.md @@ -0,0 +1,39 @@ +--- +title: Workflows & Publish Rules +description: Design Contentstack workflows and publish rules for content governance: stage design, approvals, self-approval prevention, publish governance, and automation. +--- + +# Workflows & Publish Rules + +**Slug:** `cms-workflows` · **Product:** CMS · **Type:** Advisory (read-only) + +Advises on designing workflows and publish rules that match your review process without unnecessary complexity or permission gaps. + +## When it triggers + +When you ask about workflow stage design, approval processes, publish rules, self-approval prevention, transition restrictions, or automation triggered by workflow changes. + +## What it covers + +- **Keep workflows simple**: 3–5 stages for most cases; add stages only for a clear business need. A content type can have one workflow per branch. +- **Stage design**: each stage defines who can advance entries, allowed next stages, and optional due dates/assignments. Max 20 stages; every transition is recorded in the audit log. +- **Prevent self-advancement**: requires at least two distinct reviewers; the last editor can't advance the entry. Use at least two approvers or a role with multiple members. +- **Publish rules are separate**: they govern publish/unpublish conditions independently of workflows, with scope fields (branch, content type, language, environment, action) and conditions (required stage, approver, prevent self-approval). +- **Automation**: use webhook events like `entries.workflow_stage_change`; the publish queue tracks pending actions and status. +- **Permission limitations**: only owners, admins, and developers can create workflows and publish rules. Management tokens can't change workflow stages or configure rules requiring user approval; user-scoped auth or OAuth tokens are needed for programmatic transitions. + +## Example prompts + +- "How many workflow stages should I have?" +- "How do I prevent an author from approving their own content?" +- "How do publish rules differ from workflows?" +- "Can I automate actions when content reaches a workflow stage?" +- "How do workflows work across branches?" + +## Safety notes + +Read-only advisory. Never creates, updates, publishes, unpublishes, or deletes workflows or publish rules. Use environment variables for credentials; route CMA examples through server-side proxies. + +## Related + +- [Roles & Permissions](cms-roles-permissions.md) · [Webhooks](cms-webhooks.md) · [Releases](cms-releases.md) diff --git a/docs/skills/developer-hub-app-architect.md b/docs/skills/developer-hub-app-architect.md new file mode 100644 index 0000000..d7df4cf --- /dev/null +++ b/docs/skills/developer-hub-app-architect.md @@ -0,0 +1,47 @@ +--- +title: Developer Hub App Architect +description: Turn Contentstack Developer Hub and Marketplace app ideas into concrete implementations: UI location choice, architecture, React/TypeScript scaffolding, manifest, proxy, and publishing. +--- + +# Developer Hub App Architect + +**Slug:** `developer-hub-app-architect` · **Product:** Developer Hub · **Type:** Advisor + Builder · **Ships references** + +Turns Developer Hub and Marketplace app ideas into concrete implementations: it chooses the right UI location, maps the architecture, generates boilerplate-aligned React/TypeScript code, and troubleshoots setup, SDK, manifest, proxy, and publishing issues. + +## When it triggers + +When designing or building a Contentstack Developer Hub or Marketplace app, choosing a UI location for a feature, generating app code from the boilerplate, explaining manifest/setup/proxy/OAuth/publishing steps, or debugging app loading, SDK, iframe, route, or location issues. + +## Operating modes + +- **Advisor mode**: chooses the best UI location(s) with tradeoffs, reviews architecture, and debugs issues. +- **Builder mode**: generates implementation-ready React + TypeScript with loading/error states, typed helpers, and iframe resize behavior, aligned to the user's boilerplate. + +## What it covers + +- **Location selection**: always identifies the best Contentstack UI location before writing code; prefers the smallest location that fits; compares candidates by user context, SDK surface, and complexity. +- **Developer Hub setup**: manifest, base URL, route mapping, location enabling, advanced settings variables, proxy/rewrite, install, and deploy steps. +- **SDK & integration**: `@contentstack/app-sdk` patterns for location access, config read/write, field updates, asset replacement, iframe sizing, and typed guards; proxy/API rewrites for external integrations with secrets kept server-side. +- **Troubleshooting**: checks route, manifest, location, SDK init, iframe context, config persistence, proxy behavior, and install scope, in that order, leading with the most likely cause. +- **Publishing & safety**: readiness checks for scopes, permissions, credentials, versioning, and install flow. + +## References + +Ships a Developer Hub coding reference (`references/developer-hub-coding-reference.md`) used for location selection, boilerplate conventions, SDK patterns, setup, troubleshooting, and publishing. + +## Example prompts + +- "Build a private app that adds AI suggestions in the entry sidebar." +- "Which UI location should I use for a product taxonomy picker?" +- "Generate an app configuration page and save API credentials through proxy variables." +- "Why is my app loading but `appSdk.location.CustomField` is undefined?" +- "Turn this app idea into manifest config, route plan, and starter code." + +## Safety notes + +Never exposes OAuth client secrets or app signing keys; keeps app credentials server-side via proxy variables or secure env vars. Validates installation scopes and never grants broader permissions than required. For publish/delete/revoke/uninstall flows, explains the impact first and requires confirmation of the target app/environment/installation. + +## Related + +- [Roles & Permissions](cms-roles-permissions.md) · [Tokens & Authentication](cms-tokens-authentication.md) · [Webhooks](cms-webhooks.md) diff --git a/docs/skills/dx-delivery-sdk.md b/docs/skills/dx-delivery-sdk.md new file mode 100644 index 0000000..ccd192e --- /dev/null +++ b/docs/skills/dx-delivery-sdk.md @@ -0,0 +1,55 @@ +--- +title: Delivery SDK +description: Write correct, production-ready TypeScript with @contentstack/delivery-sdk for entries, assets, references, filtering, sorting, pagination, locale, Live Preview, and Visual Builder. +--- + +# Delivery SDK + +**Slug:** `dx-delivery-sdk` · **Product:** Developer Experience · **Type:** Advisory (read-only) · **Ships references** + +Helps agents write correct, production-ready TypeScript using `@contentstack/delivery-sdk`, and verifies SDK behavior against the Delivery SDK Spec when method names, options, or chain order matter. + +## When it triggers + +When you ask for 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. + +## What it covers + +- **Stack setup**: `contentstack.stack({...})` with env-based credentials and region. +- **Single entry vs collections**: `.contentType(uid).entry(uid).fetch()` for one; `.entry().query().find()` for many. +- **References**: `includeReference([...])` belongs _before_ `.query()`. +- **Filtering**: use `QueryOperation` names exactly (e.g. `QueryOperation.EQUALS`, `NOT_EQUALS`). +- **Sorting**: `orderByAscending()` / `orderByDescending()` (never `ascending()` / `descending()`). +- **Pagination**: `.skip().limit().includeCount()`; mention the 100-item default limit when pagination is omitted. +- **Field selection**: `only()` / `except()`. +- **Assets**: direct `stack.asset(uid).fetch()` and asset queries. +- **Helper patterns**: reusable typed helpers with safe error handling. +- **Live Preview / SSR**: create a new stack per request; apply live preview config before fetching; never reuse a Live Preview stack across requests. + +### Common mistakes it prevents + +- Calling `includeReference()` after `.query()`. +- Using `ascending()` / `descending()` or `NOT_EQUAL`. +- Hardcoding credentials. +- Missing pagination on collection queries. +- Reusing a Live Preview SSR stack across requests. + +## Example prompts + +- "Set up the Contentstack Delivery SDK in TypeScript." +- "Write a query for blog posts with author references included." +- "Show the recommended SSR Live Preview setup." +- "Fix this query chain. It's not returning the right entries." +- "Create a helper to fetch entries by URL with pagination and typing." + +## References + +Ships the **Delivery SDK Spec** (`references/delivery-sdk-spec.md`), sourced from the official TypeScript Delivery SDK reference. The skill reads it on demand to verify method names, options, and chain order. + +## Safety notes + +Prefers TypeScript and current `@contentstack/delivery-sdk` APIs. Never hardcodes credentials; uses `process.env` placeholders. For SSR Live Preview, never reuses a stack across requests. Uses `@timbenniks/contentstack-endpoints` with `getContentstackEndpoints(region, true)` for region-specific preview hosts when needed. + +## Related + +- [Entries](cms-entries.md) · [Live Preview & Visual Builder Support](cms-live-preview-visual-builder-support-assistant.md) · [Migrate JS→TS SDK](dx-migrate-js-to-ts-sdk.md) diff --git a/docs/skills/dx-kickstart-next.md b/docs/skills/dx-kickstart-next.md new file mode 100644 index 0000000..98d37b7 --- /dev/null +++ b/docs/skills/dx-kickstart-next.md @@ -0,0 +1,48 @@ +--- +title: Contentstack Kickstart Next +description: Maintain Contentstack's Next.js kickstart with guidance for App Router structure, Contentstack setup, Live Preview, seeded content, environment variables, validation, and reviews. +--- + +# Contentstack Kickstart Next + +**Slug:** `dx-kickstart-next` · **Product:** Developer Experience · **Type:** Builder and review guidance · **Ships references** + +Helps agents build, review, debug, and extend Contentstack's `kickstart-next` repository or a close fork. It routes work into focused reference files for Next.js behavior, Contentstack delivery and preview setup, the seeded content model, local workflow, and PR review checks. + +## When it triggers + +When you ask about the Next.js kickstart app, 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, local setup, CI expectations, validation commands, or review checklists. + +## What it covers + +- **Next.js structure**: App Router routes, client/server boundaries, Tailwind, ESLint, TypeScript, image allowlists, and package scripts. +- **Contentstack integration**: centralized stack setup, Delivery SDK configuration, Live Preview initialization, Visual Builder edit tags, regions, hosts, and env vars. +- **Seed alignment**: `page` content type fields, modular blocks, asset shapes, CSLP `$` mappings, and renderer/type updates. +- **Workflow**: local setup, stack seeding, npm validation, docs updates, CODEOWNERS, dependency changes, and CI expectations. +- **Reviews**: blockers, major issues, minor nits, security checks, and pre-PR validation. + +## Example prompts + +- "Review my kickstart-next PR for Live Preview regressions." +- "Add a new modular block to the Next.js kickstart and keep Visual Builder working." +- "Why are my Contentstack images failing in next/image?" +- "Update the kickstart env vars for a dedicated Contentstack environment." +- "What should I run before opening a PR?" + +## References + +Ships focused reference files in `references/`: + +- `next.md` for Next.js, TypeScript, Tailwind, images, and scripts. +- `contentstack.md` for Delivery SDK setup, preview, Visual Builder, regions, hosts, and env vars. +- `content-model.md` for seeded content type and field contracts. +- `workflow.md` for setup, validation, CI, docs, and dependency work. +- `review.md` for review severity and pre-PR checks. + +## Safety notes + +Never commits real Contentstack credentials. Uses `.env.example` and docs for placeholders, keeps runtime behavior grounded in the current checkout, and verifies scripts and CI workflows before claiming they exist. + +## Related + +- [Delivery SDK](dx-delivery-sdk.md) · [Live Preview & Visual Builder Support](cms-live-preview-visual-builder-support-assistant.md) · [Data Modeling Best Practices](cms-data-modeling-best-practices.md) diff --git a/docs/skills/dx-migrate-js-to-ts-sdk.md b/docs/skills/dx-migrate-js-to-ts-sdk.md new file mode 100644 index 0000000..6cc9a73 --- /dev/null +++ b/docs/skills/dx-migrate-js-to-ts-sdk.md @@ -0,0 +1,40 @@ +--- +title: Migrate JS to TS SDK +description: Migrate Contentstack Delivery SDK code from the JavaScript SDK to the TypeScript @contentstack/delivery-sdk, preserving behavior and flagging differences. +--- + +# Migrate JS to TS SDK + +**Slug:** `dx-migrate-js-to-ts-sdk` · **Product:** Developer Experience · **Type:** Advisory (read-only) + +Migrates Contentstack Delivery SDK code from JavaScript to TypeScript: setup, initialization, Stack, Entries, Assets, Query, pagination, cache, utils, taxonomy, and image transforms: preserving behavior and calling out TypeScript-specific differences. + +## When it triggers + +When you want to migrate Delivery SDK code from JavaScript to TypeScript, compare the two SDK APIs, or get a migration-ready rewrite, side-by-side comparison, or list of breaking changes. + +## What it covers + +- **Packages & imports**: install `@contentstack/delivery-sdk@latest`; switch imports; add `@contentstack/persistance-plugin` for cache and `@contentstack/utils` for utils. +- **Key API mappings**: `contentstack.stack(...)` (not `Stack(...)`); `stack.contentType(...).entry(...).asset(...).query().fetch().find()`, plus `paginate()`, `next()`, `previous()`, `locale()`, `includeReference()`, `includeEmbeddedItems()`, `includeContentType()`, `includeCount()`, and taxonomy methods. +- **Typed results**: generics on `fetch()`. +- **Cache**: install the persistence plugin and pass `cacheOptions` for policies other than `Policy.IGNORE_CACHE`. +- **Utils**: install `@contentstack/utils` separately and call `Utils.jsonToHTML(...)`. +- **Sync**: TypeScript uses `stack.sync({ locale })` without `init: true`. +- **Limitations**: 8KB URL limit; no multiple content-type references in a single query; no direct Global Field schema querying (use `include_global_field_schema`); `assetFields` support is region-limited to NA. + +## Example prompts + +- "Migrate this JavaScript Delivery SDK code to TypeScript." +- "What changes do I need moving from `contentstack` to `@contentstack/delivery-sdk`?" +- "Show me the TypeScript equivalent for this JavaScript snippet." +- "How do I rewrite cache policy usage for the TypeScript SDK?" +- "Convert this taxonomy query from the JavaScript SDK to TypeScript." + +## Safety notes + +Never invents SDK methods not present in the reference docs. Replaces any secrets in samples with placeholders; uses environment variables for credentials. + +## Related + +- [Delivery SDK](dx-delivery-sdk.md) · [Entries](cms-entries.md) · [Taxonomy](cms-taxonomy.md) diff --git a/docs/skills/index.md b/docs/skills/index.md new file mode 100644 index 0000000..1c02782 --- /dev/null +++ b/docs/skills/index.md @@ -0,0 +1,61 @@ +--- +title: Skills reference +description: The full catalog of Contentstack Agent Skills, grouped by product. +--- + +# Skills reference + +The bundle includes 22 skills across five Contentstack products. Each links to a dedicated page with what it does, when it triggers, example prompts, and its safety notes. + +> Each skill page mirrors its canonical `skills//SKILL.md`. The slug is the skill's identifier: use it with the [`skills` CLI](../get-started/skills-cli.md). + +## CMS + +| Skill | Slug | What it helps with | +| --- | --- | --- | +| [Assets](cms-assets.md) | `cms-assets` | Asset organization, Image Delivery API transforms, publishing lifecycle, CDN behavior, limits. | +| [Branches & Aliases](cms-branches-aliases.md) | `cms-branches-aliases` | Isolated content development, alias-based zero-downtime deploys, CI/CD, merge & rollback. | +| [Data Modeling Best Practices](cms-data-modeling-best-practices.md) | `cms-data-modeling-best-practices` | Choosing content types, references, global fields, groups, modular blocks, JSON RTE, taxonomy. | +| [Entries](cms-entries.md) | `cms-entries` | CDA queries, reference expansion, pagination, versioning, publishing, bulk ops, Sync API. | +| [Environments & Publishing](cms-environments-publishing.md) | `cms-environments-publishing` | Environment design, publishing pipeline, token types, Sync API, CDN, publish queue. | +| [Localization](cms-localization.md) | `cms-localization` | Languages, fallback chains, localized vs unlocalized entries, non-localizable fields. | +| [Releases](cms-releases.md) | `cms-releases` | Atomic multi-item deployment, scheduling, webhook-storm prevention, CI/CD. | +| [Roles & Permissions](cms-roles-permissions.md) | `cms-roles-permissions` | Built-in & custom roles, permission merging, teams, token capabilities, least privilege. | +| [Taxonomy](cms-taxonomy.md) | `cms-taxonomy` | Hierarchical classification, taxonomy vs tags/labels/references, CDA taxonomy queries. | +| [Tokens & Authentication](cms-tokens-authentication.md) | `cms-tokens-authentication` | Choosing the right token, client- vs server-side safety, rate limits, SSO. | +| [Variants & Personalization](cms-variants-personalization.md) | `cms-variants-personalization` | Variants vs separate entries, variant groups, A/B testing, Personalize integration. | +| [Webhooks](cms-webhooks.md) | `cms-webhooks` | Event channels, payloads, signature verification, retries, reliable receiver design. | +| [Workflows & Publish Rules](cms-workflows.md) | `cms-workflows` | Stage design, approvals, self-approval prevention, publish governance, automation. | + +## Developer Experience + +| Skill | Slug | What it helps with | +| --- | --- | --- | +| [Delivery SDK](dx-delivery-sdk.md) | `dx-delivery-sdk` | Production-ready TypeScript with `@contentstack/delivery-sdk` for entries, assets, queries, Live Preview. | +| [Contentstack Kickstart Next](dx-kickstart-next.md) | `dx-kickstart-next` | Maintaining the Next.js kickstart: App Router, Delivery SDK setup, Live Preview, seed alignment, env vars, validation. | +| [Migrate JS→TS SDK](dx-migrate-js-to-ts-sdk.md) | `dx-migrate-js-to-ts-sdk` | Migrating Delivery SDK code from the JavaScript SDK to the TypeScript SDK. | +| [Live Preview & Visual Builder Support](cms-live-preview-visual-builder-support-assistant.md) | `cms-live-preview-visual-builder-support-assistant` | Diagnosing and implementing Live Preview / Visual Builder across CSR, SSR, SSG, BFF. | +| [Migration Companion](migration-companion.md) | `migration-companion` | Guided Contentful → Contentstack migration: content and application code. | + +## Launch + +| Skill | Slug | What it helps with | +| --- | --- | --- | +| [Sync Launch env vars from .env.example](launch-sync-environment-variables-from-env-example.md) | `launch-sync-environment-variables-from-env-example` | Comparing a local `.env.example` to a Launch environment and patching missing keys. | +| [Trigger & Monitor Deployments](launch-trigger-and-monitor-launch-deployments.md) | `launch-trigger-and-monitor-launch-deployments` | Triggering a Launch deploy, polling to completion, diagnosing failures from logs. | + +## Brand Kit + +| Skill | Slug | What it helps with | +| --- | --- | --- | +| [Brand Kit Assistant](brand-kit-assistant.md) | `brand-kit-assistant` | Brand Kit, Voice Profiles, Knowledge Vault, on-brand AI generation, governance, API routing. | + +## Developer Hub + +| Skill | Slug | What it helps with | +| --- | --- | --- | +| [Developer Hub App Architect](developer-hub-app-architect.md) | `developer-hub-app-architect` | Designing & building Developer Hub / Marketplace apps: UI locations, manifest, SDK, proxy, publishing. | + +## How skills get selected + +You don't pick skills manually for full-bundle installs: the [router](../how-it-works/router.md) matches your request automatically. Many tasks pull in more than one skill (for example, Releases + Webhooks). To force a specific skill, name it in your prompt. diff --git a/docs/skills/launch-sync-environment-variables-from-env-example.md b/docs/skills/launch-sync-environment-variables-from-env-example.md new file mode 100644 index 0000000..d198697 --- /dev/null +++ b/docs/skills/launch-sync-environment-variables-from-env-example.md @@ -0,0 +1,47 @@ +--- +title: Sync Launch env vars from .env.example +description: Compare a local .env.example with a Contentstack Launch environment and patch the environment to add any missing keys: without exposing secrets. +--- + +# Sync Launch env vars from .env.example + +**Slug:** `launch-sync-environment-variables-from-env-example` · **Product:** Launch · **Type:** Action (gated) + +Fetches environment variables from a Contentstack Launch project, compares them with a local `.env.example` file, and patches the target environment to add any missing keys. Useful for auditing missing variables before a deployment and keeping a Launch environment aligned with what a frontend project expects. + +> This skill has `disable-model-invocation: true`. It runs only when you explicitly invoke it, not via automatic routing. + +## When it triggers + +When a Launch environment must match the keys defined in a local `.env.example`, when auditing missing variables before a deployment, or when adding missing variable names without manually editing config. + +## How it works + +1. Read and parse `.env.example`, extracting variable names (ignoring comments, blanks, malformed entries). +2. Fetch the target Launch project and environment and read its current variables. +3. Compare keys: identify only missing keys unless you explicitly ask to update existing values. +4. Build a minimal patch payload with only the missing keys. +5. `PATCH /projects/{project_uid}/environments/{environment_uid}`. +6. Report missing keys, patched keys, and any errors: without exposing values. + +## Inputs + +- Launch project UID +- Launch environment UID +- Path to local `.env.example` +- Launch API credentials / authenticated context +- Optional dry-run flag + +## Example prompts + +- "Generate a Node.js script that syncs Launch environment variables from `.env.example`." +- "Compare my Launch environment variables with `.env.example` and add any missing keys." +- "Patch missing Launch environment variables for project `abc123` and environment `dev456`." + +## Safety notes + +Treats any PATCH as a destructive external action. Validates and confirms the target project/environment, and never broadens the update beyond missing keys unless asked. Prefers dry-run. Logs only key names and counts; never prints secret values from Launch or local files. Uses the smallest possible PATCH payload. + +## Related + +- [Trigger & Monitor Deployments](launch-trigger-and-monitor-launch-deployments.md) · [Environments & Publishing](cms-environments-publishing.md) diff --git a/docs/skills/launch-trigger-and-monitor-launch-deployments.md b/docs/skills/launch-trigger-and-monitor-launch-deployments.md new file mode 100644 index 0000000..a814042 --- /dev/null +++ b/docs/skills/launch-trigger-and-monitor-launch-deployments.md @@ -0,0 +1,48 @@ +--- +title: Trigger & Monitor Deployments +description: Trigger a Contentstack Launch deployment, poll it to completion, and diagnose failures from the deployment log. +--- + +# Trigger & Monitor Deployments + +**Slug:** `launch-trigger-and-monitor-launch-deployments` · **Product:** Launch · **Type:** Action (gated) + +Triggers a Launch deployment for a specific environment, polls its status until completion, and, if it fails or is cancelled, fetches the deployment log and diagnoses likely causes with next-step recommendations. Built for CI/CD or operator workflows that need a deterministic deploy status check. + +> This skill has `disable-model-invocation: true`. It runs only when you explicitly invoke it. + +## When it triggers + +When you need to automate Launch deployments for a known project and environment, monitor progress, and surface failure diagnostics. + +## How it works + +1. Validate the project and environment identifiers. +2. Confirm the target is allowed. **Require explicit approval for production**. +3. Trigger: `POST /projects/{project_uid}/environments/{environment_uid}/deployments`. +4. Poll status every 10 seconds until a terminal state. +5. Fail fast. Exit non-zero on `failed` or `cancelled`; stop polling. +6. On failure, `GET .../deployments/{deployment_uid}` for the log, then summarize the likely cause and next steps. + +## Inputs + +- `project_uid` +- `environment_uid` +- Optional deployment payload / build reference +- Confirmation for production deployments +- Any context about the app, branch, or build source + +## Example prompts + +- "Trigger a deployment for project `abc123` in environment `prod456` and watch it until it finishes." +- "Deploy the latest build to staging and tell me if it fails." +- "Poll a Launch deployment every 10 seconds and exit non-zero on failure." +- "If the deployment fails, check the logs and explain what went wrong." + +## Safety notes + +Treats deployment triggers as external side effects. Requires explicit confirmation before production deployments and never auto-deploys to production without review. Doesn't auto-retry failed deployments unless asked and the target is non-production. Never prints API tokens, deployment tokens, or environment secrets; redacts sensitive values from logs and summaries. Uses a non-zero exit code for failed or cancelled deployments. + +## Related + +- [Sync Launch env vars from .env.example](launch-sync-environment-variables-from-env-example.md) · [Branches & Aliases](cms-branches-aliases.md) · [Releases](cms-releases.md) diff --git a/docs/skills/migration-companion.md b/docs/skills/migration-companion.md new file mode 100644 index 0000000..d8a8473 --- /dev/null +++ b/docs/skills/migration-companion.md @@ -0,0 +1,51 @@ +--- +title: Migration Companion +description: Guided Contentful → Contentstack migration: content (types, entries, assets, locales) and application code: with prerequisite checks and post-migration validation. +--- + +# Migration Companion + +**Slug:** `migration-companion` · **Product:** Developer Experience · **Type:** Action (gated) · **Ships references & scripts** + +Guides a user end-to-end through migrating a project from **Contentful** to **Contentstack**: first the content (content types, entries, assets, locales) via the Contentstack CLI migrate plugin, then the website code that reads from the CMS. It's a sequential workflow where each step's output feeds the next. + +## When it triggers + +When you want to migrate, move, switch, port, or re-platform to Contentstack: content models, content, assets, locales, application integrations, or website code. Triggers on requests like "migrate to Contentstack," "move my Contentful space," or "migrate from Contentful." Contentful is currently the only supported source. + +## The migration at a glance + +| Step | What happens | Produces | +| ------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------- | +| 1. Prerequisites & inputs | Prereq checker validates Node 20+, Python 3, `csdx`, `contentful`, logins, region, spaces | Verified env + gathered inputs | +| 2. Install migrate plugin | Installs/updates `@contentstack/cli-external-migrate` | `csdx migrate:*` available | +| 3. Content migration | `csdx migrate:create` exports, converts, and imports into a new stack | Populated stack + bundle + credentials | +| 4. Code migration | Detect → plan → rewrite → eval (13 checks) | Rewritten data layer | +| 5. Welcome | : | Recap + next steps | + +## What it covers + +- **Isolated session workspace** under `/tmp/migrate-to-cs/` so concurrent runs never collide. +- **Pinned Node version**. Uses the highest installed Node ≥ 20 the checker validated. +- **Browser-based logins** for Contentstack OAuth and Contentful, handled interactively. +- **Content import** with entity-count verification (locales, content types, assets, entries imported vs exported). +- **Code rewrite** following a source-verified Contentful → Contentstack mapping reference, covering REST Delivery SDK, GraphQL, raw REST/framework plugins, rich text, assets, locales, pagination, and Live Preview. +- **Eval suite** of 13 post-migration checks (residue, field access, SDK init, build, secrets, plus review evals) that hard-gate completion. + +## References & scripts + +Ships a full `references/` mapping (`CONTENTFUL_TO_CONTENTSTACK_MIGRATION_CONTEXT.md`) and a `scripts/` suite: the prerequisite checker, import-summary parser, logging helpers, and per-check eval scripts (`run-all.sh` plus numbered checks). + +## Safety notes + +Action skill with explicit gates: confirms before logging in, before creating a stack, and before editing your code. Treats management tokens as secrets. Never echoes them or writes them to workspace files; sets `CS_*` credentials only in the migrated app's gitignored `.env`. Converts reference dereferences to safe array access and flags every guessed field UID with a `TODO(migration)` comment rather than guessing silently. + +## Example prompts + +- "Migrate my Contentful space to Contentstack." +- "Move my CMS and website code from Contentful to Contentstack." +- "Port my Contentful content models and entries to Contentstack." + +## Related + +- [Delivery SDK](dx-delivery-sdk.md) · [Migrate JS→TS SDK](dx-migrate-js-to-ts-sdk.md) · [Data Modeling Best Practices](cms-data-modeling-best-practices.md) diff --git a/manifest.json b/manifest.json index 564e68e..40cf1a3 100644 --- a/manifest.json +++ b/manifest.json @@ -1,6 +1,6 @@ { "exported_at": "2026-04-28T08:27:32.000Z", - "skill_count": 21, + "skill_count": 22, "skills": [ { "slug": "brand-kit-assistant", @@ -87,6 +87,11 @@ "title": "dx-delivery-sdk", "product": "Developer Experience" }, + { + "slug": "dx-kickstart-next", + "title": "Contentstack Kickstart Next", + "product": "Developer Experience" + }, { "slug": "dx-migrate-js-to-ts-sdk", "title": "dx-migrate-js-to-ts-sdk", diff --git a/skills/CLAUDE.md b/skills/CLAUDE.md index e86f870..abb039d 100644 --- a/skills/CLAUDE.md +++ b/skills/CLAUDE.md @@ -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) | diff --git a/skills/dx-kickstart-next/SKILL.md b/skills/dx-kickstart-next/SKILL.md new file mode 100644 index 0000000..af72619 --- /dev/null +++ b/skills/dx-kickstart-next/SKILL.md @@ -0,0 +1,34 @@ +--- +name: contentstack-kickstart-next +description: Guidance for building, reviewing, debugging, or extending Contentstack's kickstart-next repository. Use when working on the Next.js kickstart app, Contentstack Delivery SDK setup, Live Preview or Visual Builder behavior, seeded stack alignment, environment variables, endpoint or image host configuration, App Router structure, package scripts, local setup, CI expectations, tests, lint/build validation, or PR review checklists. +--- + +# 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`. diff --git a/skills/dx-kickstart-next/references/content-model.md b/skills/dx-kickstart-next/references/content-model.md new file mode 100644 index 0000000..fa8319e --- /dev/null +++ b/skills/dx-kickstart-next/references/content-model.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. diff --git a/skills/dx-kickstart-next/references/contentstack.md b/skills/dx-kickstart-next/references/contentstack.md new file mode 100644 index 0000000..8c5ae29 --- /dev/null +++ b/skills/dx-kickstart-next/references/contentstack.md @@ -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. diff --git a/skills/dx-kickstart-next/references/next.md b/skills/dx-kickstart-next/references/next.md new file mode 100644 index 0000000..91d2205 --- /dev/null +++ b/skills/dx-kickstart-next/references/next.md @@ -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. diff --git a/skills/dx-kickstart-next/references/review.md b/skills/dx-kickstart-next/references/review.md new file mode 100644 index 0000000..f00fd34 --- /dev/null +++ b/skills/dx-kickstart-next/references/review.md @@ -0,0 +1,45 @@ +# Review guidance for kickstart-next + +Use this for PR reviews, pre-PR checks, risk assessment, or summarizing changes for maintainers. + +## Review stance + +- Lead with bugs, regressions, missing validation, and security risks. +- Ground findings in file and line references when reviewing a local checkout. +- Separate blockers, major issues, and minor nits. +- Keep summaries secondary to findings. + +## Blockers + +- Secrets or real Contentstack credentials committed anywhere. +- Build or lint failures caused by the change. +- Broken production home route or preview route. +- Live Preview or Visual Builder field binding regressions. +- XSS regression from unsanitized rich text or unsafe `dangerouslySetInnerHTML`. +- Content type UID, field UID, or modular block changes that are not reflected in types/renderers/docs. + +## Major issues + +- New environment variables missing from `.env.example` or setup docs. +- New remote image hostnames not represented in `next.config.mjs`. +- Moving Contentstack setup out of `lib/contentstack.ts` without a clear simplification. +- Client-only preview code introduced into server execution paths. +- Dependency additions that are unnecessary for a minimal kickstart or likely to fail security scans. +- CI claims that do not match `.github/workflows`. + +## Minor issues + +- Overly complex abstractions in example code. +- Copy or README changes that make setup less direct. +- Styling changes that distract from the kickstart's purpose as a minimal Contentstack integration example. +- Type looseness where existing Contentstack types could be extended cleanly. + +## Pre-PR checklist + +- Run `npm run build`. +- Run `npm run lint` if present. +- Run any `typecheck` or `test` scripts only if present. +- Verify `.env.example` and docs for env changes. +- Scan the diff for secrets. +- Read `references/content-model.md` for schema-impacting changes. +- Check preview behavior if data fetching, CSLP `$` attributes, components, content model fields, or Live Preview initialization changed. diff --git a/skills/dx-kickstart-next/references/workflow.md b/skills/dx-kickstart-next/references/workflow.md new file mode 100644 index 0000000..81e5378 --- /dev/null +++ b/skills/dx-kickstart-next/references/workflow.md @@ -0,0 +1,46 @@ +# Workflow guidance for kickstart-next + +Use this for setup, seeding, environment variables, validation commands, CI expectations, docs updates, dependency changes, or PR prep. + +## Local setup + +- Prefer npm: install with `npm install`. +- Copy `.env.example` to `.env` and fill in Contentstack values locally. +- Run the app with `npm run dev`, then open `http://localhost:3000`. +- For production verification, run `npm run build` and then `npm run start` if runtime behavior needs manual checking. + +## Contentstack stack setup + +- Install the Contentstack CLI with `npm install -g @contentstack/cli` if the user needs to seed a stack. +- Configure the CLI region when prompted; free developer accounts are commonly EU, but verify the user's account/URL. +- Login with `csdx auth:login`. +- Seed the compatible model with `csdx cm:stacks:seed --repo "contentstack/kickstart-stack-seed" --org "" -n "Kickstart Stack"`. +- Create a delivery token with preview scope and a preview token when Live Preview is needed. +- Enable Live Preview in the stack settings for the preview environment. + +## Validation + +- After JavaScript or TypeScript edits, run `npm run build`. +- Run `npm run lint` when the script exists. +- Run `npm run typecheck` only if `package.json` defines it. +- Run tests only if the checkout defines test scripts or test tooling. The upstream kickstart currently has no default `test` script. +- If validation cannot run because Contentstack credentials are unavailable, report that clearly and still run static checks that do not require credentials. + +## Environment and docs + +- When adding or renaming environment variables, update `.env.example` and user-facing setup docs together. +- Document runtime behavior changes in `docs/` when the repository has or needs product-facing docs for that behavior. +- Keep README setup snippets short and copyable. +- Never commit real API keys, delivery tokens, preview tokens, management tokens, organization IDs, or stack IDs. + +## CI expectations + +- Verify `.github/workflows` before making CI claims. +- Upstream workflows focus on security/policy checks such as Snyk/SCA, security policy/license checks, and issue-to-Jira integration. +- Do not assume GitHub Actions runs `npm run build`, `npm run lint`, unit tests, or E2E tests unless a workflow in the checkout proves it. + +## Ownership and dependencies + +- Check `.github/CODEOWNERS` before making reviewer or ownership claims. +- Dependency changes can affect Snyk/SCA workflows; keep package lock changes intentional and explain why a dependency is needed. +- Prefer npm for dependency installation and lockfile updates.