content-modeling-best-practices by sanity-io | skilld
[Skip to main content](#main-content)
[skilld](https://skilld.dev/)
[Skills](https://skilld.dev/skills) [Collections](https://skilld.dev/collections)
[Sign in](https://skilld.dev/login)
[All skills](https://skilld.dev/skills)
[sanity-io/agent-toolkit repository](https://skilld.dev/gh/sanity-io/agent-toolkit)
# /content-modeling-best-practices
official
[sanity-io](https://skilld.dev/gh/sanity-io)/ [agent-toolkit](https://skilld.dev/gh/sanity-io/agent-toolkit) 149 20
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.
802/wk Updated 4 days ago [ Trust](#receipts "View trust signals: audits, signed commits, source provenance")
[sanity](https://skilld.dev/skills/tag/sanity) [ headless-cms](https://skilld.dev/skills/tag/headless-cms) [ content-modeling](https://skilld.dev/skills/tag/content-modeling) [ schema-design](https://skilld.dev/skills/tag/schema-design) [ content-architecture](https://skilld.dev/skills/tag/content-architecture) [ references](https://skilld.dev/skills/tag/references) [ taxonomies](https://skilld.dev/skills/tag/taxonomies) [ structured-content](https://skilld.dev/skills/tag/structured-content)
## Install
skilld
skills.sh
`npx -y skilld add gh:sanity-io/agent-toolkit -s content-modeling-best-practices`
[GitHub](https://github.com/sanity-io/agent-toolkit) [skills.sh](https://skills.sh/sanity-io/content-modeling-best-practices) [Raw](https://skilld.dev/api/skills-raw/sanity-io/agent-toolkit/content-modeling-best-practices)
## Files
- [SKILL.md](https://skilld.dev/gh/sanity-io/agent-toolkit/content-modeling-best-practices)
## Skill content
Copy markdown
Preview
Raw
## 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
Source: [SKILL.md on GitHub](https://github.com/sanity-io/agent-toolkit/blob/ad50ea46c430c68df8dc4d08d43ae6ac1c1aa4f1/skills/content-modeling-best-practices/SKILL.md)
## What it does
Guides schema design for Sanity and headless CMSes through principles like content-as-data, single source of truth, and editor-centric structure. Covers references vs embedded objects, separation of concerns, content reuse patterns, and taxonomy design to avoid page-shaped or presentation-driven schemas.
Generated from this skill's SKILL.md.
## Frequently asked
Does this skill apply to CMSes other than Sanity?
Yes. The skill covers general content modeling principles that apply to any headless CMS, with Sanity-specific implementation notes included where relevant.
What specific decisions does this skill help with?
It guides decisions on schema design, references versus embedded objects, content reuse patterns, taxonomy structures, and whether a model is too page-shaped or presentation-driven.
Does this skill provide code examples or just principles?
The skill provides structured guidance documents covering separation of concerns, reference vs embedding, content reuse, and taxonomy classification. It is principles-focused rather than code-focused.
Can I use this when refactoring an existing content model?
Yes. The skill is designed for both new projects and refactoring existing structures to improve reusability and flexibility.
Generated from the skill's SKILL.md. Refreshed when the source changes.
## Install
skilld
skills.sh
`npx -y skilld add gh:sanity-io/agent-toolkit -s content-modeling-best-practices`
[GitHub](https://github.com/sanity-io/agent-toolkit) [skills.sh](https://skills.sh/sanity-io/content-modeling-best-practices) [Raw](https://skilld.dev/api/skills-raw/sanity-io/agent-toolkit/content-modeling-best-practices)
## Metadata
- Description
- 441 chars · frontmatter
- Frontmatter
- 2 keys
## Files
- [SKILL.md](https://skilld.dev/gh/sanity-io/agent-toolkit/content-modeling-best-practices)
## Trust
Verified 4 days ago · stale
No third-party audits yet.
Active
[ad50ea4](https://github.com/sanity-io/agent-toolkit/commit/ad50ea46c430c68df8dc4d08d43ae6ac1c1aa4f1 "ad50ea46c430c68df8dc4d08d43ae6ac1c1aa4f1")· updated 2 months ago
[SKILL.md ](https://github.com/sanity-io/agent-toolkit/blob/ad50ea46c430c68df8dc4d08d43ae6ac1c1aa4f1/skills/content-modeling-best-practices/SKILL.md) [ History ](https://github.com/sanity-io/agent-toolkit/commits/main/skills/content-modeling-best-practices/SKILL.md)
## Related skills
From sanity-io/agent-toolkit
[ /sanity-best-practices sanity-io/agent-toolkit Sanity development best practices for schema design, GROQ queries, TypeGen, Visual Editing, images, Portable Text, Studio structure, localization, migrations, Sanity Functions, Blueprints, and framework integrations such as Next.js, Nuxt, Astro, Remix, SvelteKit, Angular, Hydrogen, and the App SDK. Use this skill whenever working with Sanity schemas, defineType or defineField, GROQ or defineQuery, content modeling, Presentation or preview setups, Sanity-powered frontend integrations, Sanity Functions, documentEventHandler, defineDocumentFunction, defineMediaLibraryAssetFunction, @sanity/functions, @sanity/blueprints, sanity.blueprint.ts, event-driven content automation, or when reviewing and fixing a Sanity codebase.](https://skilld.dev/gh/sanity-io/agent-toolkit/sanity-best-practices) [ /seo-aeo-best-practices sanity-io/agent-toolkit SEO and AEO best practices for metadata, Open Graph, sitemaps, robots.txt, hreflang, JSON-LD structured data, EEAT, and content optimized for search engines and AI answer surfaces. Use this skill when implementing page SEO, technical SEO, schema markup, international SEO, AI-overview readiness, or improving content for Google, ChatGPT, Perplexity, and similar assistants.](https://skilld.dev/gh/sanity-io/agent-toolkit/seo-aeo-best-practices) [ /content-experimentation-best-practices sanity-io/agent-toolkit Content experimentation and A/B testing guidance covering experiment design, hypotheses, metrics, sample size, statistical foundations, CMS-managed variants, and common analysis pitfalls. Use this skill when planning experiments, setting up variants, choosing success metrics, interpreting statistical results, or building experimentation workflows in a CMS or frontend stack.](https://skilld.dev/gh/sanity-io/agent-toolkit/content-experimentation-best-practices) [ /portable-text-conversion sanity-io/agent-toolkit Convert HTML and Markdown content into Portable Text blocks for Sanity. Use when migrating content from legacy CMSs, importing HTML or Markdown into Sanity, building content pipelines that ingest external content, converting rich text between formats, or programmatically creating Portable Text documents. Covers @portabletext/markdown (markdownToPortableText), @portabletext/block-tools (htmlToBlocks), custom deserializers, and the Portable Text specification for manual block construction.](https://skilld.dev/gh/sanity-io/agent-toolkit/portable-text-conversion) [ /portable-text-serialization sanity-io/agent-toolkit Render and serialize Portable Text to React, Svelte, Vue, Astro, HTML, Markdown, and plain text. Use when implementing Portable Text rendering in any frontend framework, building custom serializers for non-standard block types, converting Portable Text to HTML strings server-side, converting Portable Text to Markdown, extracting plain text from Portable Text, or troubleshooting rendering issues with marks, blocks, lists, or custom types.](https://skilld.dev/gh/sanity-io/agent-toolkit/portable-text-serialization)
[Stats](https://skilld.dev/skills/stats) [Accessibility](https://skilld.dev/accessibility)
[GitHub repository (opens in new tab)](https://github.com/harlan-zw/skilld)
Built by [Harlan Wilton](https://harlanzw.com)