Content Modeling Best Practices

From the author

Structured content modeling guidance for schema design, content architecture, content reuse, references versus embedded objects, separation of concerns, and taxonomies across Sanity and other headless CMSes. Use this skill when designing or refactoring content types, deciding field shapes, debating reusable versus nested content, planning omnichannel content models, or reviewing whether a schema is too page-shaped or presentation-driven.

— the description by Sanity

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a framework for designing structured content models that prioritize data integrity and reusability over presentation-driven layouts. It offers guidance on core architectural decisions, such as when to use references versus embedded objects, how to implement shared components, and strategies for managing taxonomies. While applicable to any headless CMS, it includes specific implementation patterns for Sanity, helping developers build systems that are future-proof and optimized for content editors.

What it does

Defines principles for separating content from presentation layers.
Provides decision frameworks for choosing between references and embedded objects.
Outlines patterns for content reuse, including shared components and field sets.
Offers guidance on structuring taxonomies for consistent content classification.
Helps identify and avoid common anti-patterns like over-abstraction.
Supports planning for omnichannel content delivery.

When to use it

When starting a new project and designing the initial content model.
When evaluating whether content should be structured or free-form.
When deciding between using references or embedding content directly.
When planning for multi-channel content delivery requirements.
When refactoring existing content structures to improve maintainability.

Advantages

Promotes a single source of truth to reduce content duplication.
Improves editor experience by streamlining content management workflows.
Ensures content is flexible enough for future, unknown delivery channels.
Reduces query complexity by applying appropriate modeling patterns.
Provides clear, actionable implementation examples for schema design.

Usage examples

“Should I use a reference or an embedded object for author profiles in my blog?”: The agent explains that author profiles should be referenced because they are reusable, need central management, and have their own lifecycle independent of individual blog posts.
“How can I avoid repeating SEO fields across my page and post types?”: The agent provides a pattern for creating a shared field set that can be spread into multiple document types, ensuring consistency and reducing code duplication.
“What are the signs that my content model is over-abstracted?”: The agent lists indicators such as references used only once, editors needing to navigate multiple documents for a single page, and complex queries joining rarely-shared content.
“How do I handle a product that needs to be referenced but occasionally requires a custom title?”: The agent suggests a hybrid approach using an object that contains both a reference to the canonical product and an optional override field for the title.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/sanity-io/content-modeling-best-practices/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip content-modeling-best-practices.zip -d .agents/skills

Documentation by Sanity

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

References

Start with the reference that matches the modeling decision in front of you, instead of loading every topic at once. See references/ for detailed guidance on specific topics:

references/separation-of-concerns.md — Separating content from presentation
references/reference-vs-embedding.md — When to use references vs embedded objects
references/content-reuse.md — Content reuse patterns and the reuse spectrum
references/taxonomy-classification.md — Flat, hierarchical, and faceted classification

Files

ATTRIBUTION.mdAdded by AutoGineer893 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md1.8 KiB
references/content-reuse.md2.9 KiB
references/reference-vs-embedding.md2.3 KiB
references/separation-of-concerns.md2.1 KiB
references/taxonomy-classification.md3.3 KiB

references/reference-vs-embedding.md

Reference vs Embedding Content

When should content be linked (referenced) vs copied (embedded)? This decision affects reusability, query complexity, and editing workflows.

The Trade-offs

Aspect	Reference	Embedded Object
Reusability	✅ Shared across documents	❌ Copied per document
Single source	✅ Update once, reflects everywhere	❌ Must update each copy
Query complexity	Requires joins/expansion	Inline, simpler queries
Editing UX	Separate editing interface	All fields in one place
Independence	Can exist on its own	Only exists within parent

When to Reference

Use references when content:

Is reusable — Same author across many articles
Needs central management — Update product info once
Has its own lifecycle — Published/draft independent of parent
Should stay in sync — Price changes reflect everywhere

Examples:

Author profiles
Product catalog items
Shared testimonials
Category taxonomy
Reusable CTAs

When to Embed

Use embedded objects when content:

Is unique to this document — Page-specific hero
Doesn't make sense alone — SEO metadata
Should be copied, not linked — Historical snapshot
Simplifies editing — All fields in one form

Examples:

SEO metadata
Page-specific sections
Address information
Social links
Configuration options

Sanity Implementation

// Reference: Author is reusable
defineField({
  name: 'author',
  type: 'reference',
  to: [{ type: 'author' }]
})

// Embedded: SEO is page-specific
defineField({
  name: 'seo',
  type: 'object',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'description', type: 'text' })
  ]
})

The Hybrid Approach

Sometimes you want both: a reference for the canonical data, plus embedded overrides.

defineField({
  name: 'featuredProduct',
  type: 'object',
  fields: [
    defineField({ 
      name: 'product', 
      type: 'reference', 
      to: [{ type: 'product' }] 
    }),
    defineField({ 
      name: 'overrideTitle', 
      type: 'string',
      description: 'Optional: Override the product title for this context'
    }),
  ]
})

Query uses coalesce(overrideTitle, product->title).

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Setup TS Deep Modules
Matt Pocock· Community
Configures dependency-cruiser to enforce deep module boundaries in TypeScript repositories.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskHas scriptsGitHub stars of the source repository317.5k
To Spec
Matt Pocock· Community
Synthesizes conversation context into a structured technical specification and publishes it to a project issue tracker.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Improve Codebase Architecture
Matt Pocock· Community
A systematic process to identify, visualize, and refine architectural deepening opportunities in a codebase.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Domain Modeling
Matt Pocock· Community
An expert assistant for defining project terminology, maintaining a glossary, and documenting architectural decisions.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Codebase Design
Matt Pocock· Community
A shared vocabulary and set of principles for designing deep, testable, and maintainable software modules.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Prototype
Matt Pocock· Community
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download content-modeling-best-practices.zip