playbooks

home / skills / sanity-io / agent-toolkit / content-modeling-best-practices

content-modeling-best-practices skill

/skills/content-modeling-best-practices

This skill helps you design structured, reusable content models across CMSs, with Sanity-specific guidance to future-proof and improve editorial workflows.

npx playbooks add skill sanity-io/agent-toolkit --skill content-modeling-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1.5 KB
---
name: content-modeling-best-practices
description: General principles for structured content modeling that apply across CMSs, with Sanity-specific guidance. Use when designing content schemas, planning content architecture, or evaluating content reuse strategies.
license: MIT
metadata:
  author: sanity
  version: "1.0.0"
---

# Content 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

1. **Content is data, not pages** — Structure content for meaning, not presentation
2. **Single source of truth** — Avoid content duplication
3. **Future-proof** — Design for channels that don't exist yet
4. **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 presentation
- `resources/reference-vs-embedding.md` — When to use references vs embedded objects
- `resources/content-reuse.md` — Content reuse patterns and the reuse spectrum
- `resources/taxonomy-classification.md` — Flat, hierarchical, and faceted classification

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

FAQ

When should I choose references over embedding?

Choose references when the same entity is reused or updated independently. Embed when the data is small, specific to the parent, and unlikely to be shared.

How do I keep editors productive while enforcing structure?

Provide sensible defaults, clear field descriptions, validation rules, and curated previews. Use grouping and helper text to reduce cognitive load.