Skills sanity-io agent-toolkit
content-modeling-best-practices
- Use it when:
- You're designing or refactoring a CMS's content types, or a schema looks shaped like pages instead of content.
- It does:
- Loads the one reference that fits the decision: separating content from presentation, references versus embedding, reuse, or taxonomies.
- You get:
- Principles with good and bad examples, a Sanity schema snippet for each, and common mistakes to avoid.
- Rule of thumb:
- If the site were redesigned, the field names should still make sense: headline, not bigHeroText.
TL;DR
Sanity's guide to structured content, written for any headless CMS. Its four principles: content is data, not pages; keep one source of truth; design for channels that don't exist yet; and optimize for the editors. Separating content from presentation means names such as callout or tone instead of blueHighlightBox or backgroundColor, leaving the look to the frontend. References suit content that is reused, managed centrally, has its own lifecycle or must stay in sync, such as authors or products; embedded objects suit content unique to one document, such as a page's hero or SEO fields; a hybrid keeps a reference plus local overrides. Reuse runs from full duplication to full reference, through shared components, shared field sets, taxonomy references and content fragments, and it warns against over-abstraction, such as references used only once. Taxonomies can be flat, hierarchical or faceted, with advice on naming, depth, queries and governance.
Summarizes the skill at 3ed3a14.
npx skills add https://github.com/sanity-io/agent-toolkit --skill content-modeling-best-practices skills.sh pageSource on GitHubAll skills from sanity-io/agent-toolkit
- Total Downloads
- 5,000 on skills.sh, Nov 9, 2026
- Repo stars
- 197 sanity-io/agent-toolkit
- First seen
- Jan 24, 2026 on skills.sh
Weekly values
| Week to | Installs |
|---|---|
| Sep 21 | 128 |
| Sep 28 | 99 |
| Oct 5 | 106 |
| Oct 12 | 118 |
| Oct 19 | 84 |
| Oct 26 | 102 |
| Nov 2 | 109 |
| Nov 9 | 80 |
| Category |
Test-first work, implementation from specs, git hygiene and scope control. Guides for frameworks, databases and SDKs, mostly from their vendors. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills. |
|---|---|
| Type |
Knowledge and rules the agent applies while it works: best practices, design principles, API references. |
| Effect |
Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code. |
| Needs |
Instructions only. Works in any agent that supports skills. |
| Publisher |
A verified publisher on skills.sh, or the company or maintainer behind the product the skill operates. |
| Topics | |
| Stack |
SKILL.md
From sanity-io/agent-toolkit at 3ed3a14. Checked daily, last changed Nov 7, 2026.
Frontmatter
name: content-modeling-best-practices
description: 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.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
- 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 presentationreferences/reference-vs-embedding.md— When to use references vs embedded objectsreferences/content-reuse.md— Content reuse patterns and the reuse spectrumreferences/taxonomy-classification.md— Flat, hierarchical, and faceted classification