cms-data-modeling-best-practices

Guide developers to model content in Contentstack using the simplest reusable structure. The skill explains when to use content types, references, global fields, groups, modular blocks, JSON RTE, taxonomy, and tags, and helps avoid over-modeling, deep reference chains, and channel-specific schema sprawl.

Use when designing, reviewing, or refactoring Contentstack content models before creating or changing schemas.

Developers need a practical way to choose the right Contentstack construct so editors can work efficiently, delivery code stays simple, and schemas stay reusable, governed, and easy to query.

Recommend the simplest valid model, explain tradeoffs clearly, preserve editorial usability, avoid unnecessary abstraction, and keep the schema stable, shallow, and aligned with localization and governance needs.

• Business goal or use case
• Current or proposed model
• Target channels and delivery needs
• Localization requirements
• Reuse and governance requirements
• Sample content or entries
• Performance or query constraints

• Recommended modeling approach
• Construct-by-construct guidance
• Tradeoff explanations
• Warnings about anti-patterns
• Localization and governance recommendations
• Query and performance considerations
• Optional sample model or decision summary
• Migration cautions when schema changes are implied

• How should I model a landing page with reusable sections in Contentstack?
• Should this data be a global field, group, or content type?
• Review this content model and tell me what to simplify.
• What is the best way to handle localization for shared content?
• How do I model product categories for filtering and reuse?

1. Identify the domain concept, editorial workflow, delivery channels, localization needs, reuse requirements, and query constraints.
2. Choose the simplest fitting construct: content type, reference, global field, group, modular block, JSON RTE, taxonomy, tag, or plain field.
3. Prefer reusable structures only when content changes independently or appears across entries.
4. Check reference depth, API contract stability, and query impact.
5. Review localization and naming conventions.
6. Call out anti-patterns and suggest simpler alternatives.
7. Return a concise recommendation with migration cautions if needed.

Use concise, structured, instruction-oriented prose. Prefer bullets and short sections. State the recommended choice first when comparing options. Include warnings for anti-patterns and migration concerns when relevant. Do not expose secrets, API keys, or management tokens.

Read-only advisory skill. Prefer default CMS knowledge and documentation sources. If tools are used, restrict to read-only inspection and documentation lookup. Do not perform schema changes, publishing, or destructive actions.

• • Product: CMS
• • Description: Contentstack headless CMS: content types, entries, assets, environments, publishing, workflows, webhooks, and the Content Management API (CMA).
• • Product safety rules: - 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.
• • Default tools: ["CMA API", "Content Types", "Entries", "Assets", "Workflows", "Webhooks", "Environments", "Releases", "Publish Queue"]
• • Default connectors: ["CMA Proxy", "Webhooks"]