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.

referencestaxonomy-classification.md

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

Taxonomy and Classification

Organizing content with taxonomies enables filtering, navigation, and content relationships. Well-designed taxonomies scale; poorly designed ones become maintenance nightmares.

Types of Classification

Flat Taxonomy

Simple list of terms with no hierarchy.

Use for: Tags, simple categories Example: Blog tags: "javascript", "react", "tutorial"

defineType({
  name: 'tag',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'slug', type: 'slug' }),
  ]
})

Hierarchical Taxonomy

Terms with parent-child relationships.

Use for: Product categories, content sections Example: Electronics > Phones > Smartphones

defineType({
  name: 'category',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string' }),
    defineField({ name: 'slug', type: 'slug' }),
    defineField({ 
      name: 'parent', 
      type: 'reference', 
      to: [{ type: 'category' }],
      description: 'Parent category (leave empty for top-level)'
    }),
  ]
})

Faceted Classification

Multiple independent dimensions.

Use for: Complex filtering (e-commerce) Example: Filter by color AND size AND price range

// Multiple taxonomy types
defineField({ name: 'color', type: 'reference', to: [{ type: 'color' }] })
defineField({ name: 'size', type: 'reference', to: [{ type: 'size' }] })
defineField({ name: 'material', type: 'reference', to: [{ type: 'material' }] })

Design Principles

1. Mutual Exclusivity (When Appropriate)

Categories should be distinct. If items frequently belong to multiple categories, consider tags instead.

Categories: One primary classification Tags: Many optional classifications

2. User-Centric Naming

Use terms your audience uses, not internal jargon.

Bad: "Content Assets" (internal term) Good: "Resources" or "Downloads" (user term)

3. Balanced Depth

Too shallow: Everything lumped together Too deep: Users can't find anything

Rule of thumb: 3-4 levels max for hierarchies

4. Scalable Structure

Design for 10x growth. Will your structure work with 10,000 items?

Querying Taxonomies

Get all items in a category

*[_type == "product" && category._ref == $categoryId]

Get items in category OR children

// First get all descendant category IDs
*[_type == "product" && category._ref in 
  *[_type == "category" && (
    _id == $categoryId || 
    parent._ref == $categoryId ||
    parent->parent._ref == $categoryId
  )]._id
]

Get category tree

*[_type == "category" && !defined(parent)]{
  title,
  slug,
  "children": *[_type == "category" && parent._ref == ^._id]{
    title,
    slug,
    "children": *[_type == "category" && parent._ref == ^._id]{
      title,
      slug
    }
  }
}

Common Mistakes

Over-categorization

Creating a category for everything results in mostly-empty categories.

Fix: Start minimal, add categories as content grows.

Inconsistent Granularity

Some categories broad ("Technology"), others narrow ("React 18 Server Components").

Fix: Define clear criteria for category creation.

No Governance

Anyone can create taxonomy terms, leading to duplicates and inconsistency.

Fix: Limit who can create/edit taxonomy documents. Use validation.

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