AutoGineer
Generated banner for Content Modeling Best Practices
Generated logo for Content Modeling Best Practices

Content Modeling Best Practices

SanityOfficialPublished by Sanity

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/sanity-io/content-modeling-best-practices/download

  2. 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

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

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

LICENSE

MIT License

Copyright (c) 2025 Sanity

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

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.

Attribution and licence

Published by
Sanity
Publisher
Sanity (Official)
Source
sanity-io/agent-toolkit · skills/content-modeling-best-practices · commit 3ed3a14
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Sanity or Sanity.

Download ZIP

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