Index of every page on this site: llms.txt
All skills
robotostudio avatar

/content-modeling-best-practices

@c0b29e4
Run it yourself

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.

  • 5 files
  • 12.5 KB
  • Updated 6 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/robotostudio/turbo-start-sanity/content-modeling-best-practices

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesreference-vs-embedding.md

≈586 tokens on demand. Your agent reads this file only when SKILL.md points to it.

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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at c0b29e4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago

README badge

README badge for robotostudio/turbo-start-sanity/content-modeling-best-practices