content-modeling-best-practices_skill

Overview

This skill captures practical principles for designing structured content models that are flexible, reusable, and maintainable across headless CMSs, with targeted guidance for Sanity implementations. It focuses on treating content as data, minimizing duplication, and optimizing for editors and future channels. Use it to inform schema decisions, content architecture, and reuse strategies.

How this skill works

The skill inspects schema decisions and content patterns against core principles: treating content as data rather than presentation, choosing references vs embedding, and enforcing single sources of truth. It highlights Sanity-specific patterns (document types, references, arrays, portable text) and recommends where to apply them. The result is a set of concrete recommendations to improve content reuse, editorial workflows, and multi-channel readiness.

When to use it

• Starting a new project and defining the content model
• Deciding whether content should be structured or free-form
• Choosing between references and embedded objects for reuse
• Planning content for multi-channel delivery (web, apps, feeds)
• Refactoring legacy content to reduce duplication and improve maintainability

Best practices

• Model content as data: separate content from presentation and capture meaning with fields and relationships
• Favor references for reusable content and rich entities; embed simple, tightly coupled data
• Design editor-friendly schemas: clear field names, helpful descriptions, and validation rules
• Maintain a single source of truth: avoid duplicating the same content across documents
• Plan for unknown channels: include metadata, alternative text, and structured summaries
• Use Sanity features intentionally: documents for main entities, references for relations, arrays for ordered content, and portable text for rich body content

Example use cases

• Designing a product catalog where product specs are referenced by multiple landing pages
• Building a blog with reusable author profiles and tag taxonomies to avoid duplication
• Refactoring a marketing site so hero sections are data-driven components referenced from pages
• Preparing content for omnichannel delivery by adding structured summaries and alt text
• Creating a modular component library in Sanity where components are authored as portable data