content-modeling-best-practices
npx machina-cli add skill sanity-io/agent-toolkit/content-modeling-best-practices --openclawContent Modeling Best Practices
Principles for designing structured content that's flexible, reusable, and maintainable. These concepts apply to any headless CMS but include Sanity-specific implementation notes.
When to Apply
Reference these guidelines when:
- Starting a new project and designing the content model
- Evaluating whether content should be structured or free-form
- Deciding between references and embedded content
- Planning for multi-channel content delivery
- Refactoring existing content structures
Core Principles
- Content is data, not pages — Structure content for meaning, not presentation
- Single source of truth — Avoid content duplication
- Future-proof — Design for channels that don't exist yet
- Editor-centric — Optimize for the people creating content
Resources
See resources/ for detailed guidance on specific topics:
resources/separation-of-concerns.md— Separating content from presentationresources/reference-vs-embedding.md— When to use references vs embedded objectsresources/content-reuse.md— Content reuse patterns and the reuse spectrumresources/taxonomy-classification.md— Flat, hierarchical, and faceted classification
Source
git clone https://github.com/sanity-io/agent-toolkit/blob/main/skills/content-modeling-best-practices/SKILL.mdView on GitHub Overview
This guide presents principles for designing structured content that’s flexible, reusable, and maintainable across CMSs, with Sanity-specific guidance. Use it when designing content schemas, planning architecture, or evaluating content reuse strategies.
How This Skill Works
It emphasizes treating content as data, maintaining a single source of truth, and designing for future channels. The guidance covers when to use references versus embedded content and centers on editor-friendly workflows to improve content quality and reuse.
When to Use It
- Starting a new project and designing the content model
- Evaluating whether content should be structured or free-form
- Deciding between references and embedded content
- Planning for multi-channel content delivery
- Refactoring existing content structures
Quick Start
- Step 1: Map content to data-first document types and define top-level references (e.g., author, category, asset)
- Step 2: Choose references for reusable entities and embed content only when tightly coupled and unlikely to change
- Step 3: Architect for multi-channel delivery and establish a clear content reuse strategy with editors
Best Practices
- Content is data, not pages — structure content for meaning and relationships, not presentation
- Single source of truth — avoid duplicating content across documents or fields
- Future-proof — design for channels and formats that don’t exist yet
- Editor-centric — optimize schemas for content creators and editors
- Separation of concerns and reuse — plan for reusable components, taxonomy, and clear boundaries between content and presentation
Example Use Cases
- Design a blog schema with a separate author document and a reusable tag taxonomy to enable cross-post reuse
- Plan product content for multi-channel delivery (web, mobile, and apps) using shared product references
- Refactor a large site from free-form blocks to structured blocks with reusable components to reduce duplication
- Use references for shared marketing copy (benefits, features) to avoid content drift across pages
- Implement flat, hierarchical, or faceted classification to support flexible navigation and search
