content-modeling-best-practices

The content-modeling-best-practices skill provides structured guidance for designing, evaluating, and refactoring content models in headless CMS environments. Its primary purpose is to help teams create content architectures that are flexible, reusable, and maintainable over time. Rather than treating content as page-specific structures, the skill promotes modeling content as structured data, enabling organizations to avoid duplication, establish a single source of truth, and support future content delivery needs across multiple channels. The guidance is applicable to Sanity as well as other headless CMS platforms.

The skill focuses on foundational content modeling decisions and architectural best practices. It covers schema design, content architecture, content reuse strategies, and the tradeoffs between references and embedded content. It also provides guidance on separating content from presentation, designing for omnichannel delivery, and organizing information through taxonomies and classification systems. Additional reference materials address key topics such as separation of concerns, reference-versus-embedding decisions, content reuse patterns, and approaches to flat, hierarchical, and faceted classification.

This skill is intended for content architects, CMS implementers, developers, technical leads, and teams responsible for structured content design. It is particularly useful when starting a new project, reviewing an existing schema, planning content for multiple delivery channels, or determining whether content should be structured or free-form. The guidance helps stakeholders make informed modeling decisions while keeping editor workflows, maintainability, and long-term scalability in mind.