content-modeling-best-practices

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.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/content-modeling-best-practices/SKILL.md

Quality

Content

47%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a concise, well-organized overview that uses progressive disclosure effectively to route to detailed reference files. Its weakness is actionability and workflow clarity: it states principles and situational triggers but lacks concrete executable guidance, sequenced steps, or validation checkpoints.

Suggestions

Add a concrete worked example (e.g., a sample Sanity schema snippet showing a reference field vs an embedded object) so the body gives executable guidance rather than only abstract principles.

Turn the "When to Apply" list into a short decision procedure (e.g., 'If the content appears on >1 channel → model it as reusable; if it is presentation-specific → keep it as a field') with a clear sequence.

Include a brief validation/review step for refactoring scenarios (e.g., 'Re-check that no content is duplicated across types and that every field is meaning-based, not presentation-based') to add a checkpoint for batch/destructive schema changes.

Dimension	Reasoning	Score
Conciseness	The body is lean with no padding of concepts Claude already knows; only mildly editorial phrases like "These concepts apply to any headless CMS but include Sanity-specific implementation notes" keep it just short of the 'lean and efficient, every token earns its place' anchor.	4 / 5
Actionability	Guidance is high-level and principle-driven ("Content is data, not pages", "Avoid content duplication") with no concrete commands, schemas, or executable examples in the body, matching the 'minimal concrete guidance; high-level hints but missing specific steps' anchor.	2 / 5
Workflow Clarity	The "When to Apply" list offers rough situational triggers rather than a sequenced multi-step process, and there are no validation checkpoints, fitting the 'rough sequence present but many gaps; validation absent' anchor.	2 / 5
Progressive Disclosure	A clear overview body signals one-level-deep references to real files (e.g. `references/separation-of-concerns.md`, `references/reference-vs-embedding.md`) with short descriptors, though the reference list is prose rather than a tight bulleted index, leaving minor organization gaps.	4 / 5
	Total	12 / 20 Passed

Description

83%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, well-targeted description that clearly states the domain and provides an explicit "Use when" trigger with concrete scenarios. It is specific and distinct, with only minor gaps in synonym coverage and slight overlap risk against broad CMS/data-modeling skills.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions — "designing or refactoring content types, deciding field shapes, debating reusable versus nested content, planning omnichannel content models, reviewing whether a schema is too page-shaped" — with only minor coverage gaps, matching the 'several specific actions' anchor.	4 / 5
Completeness	Explicitly answers both what the skill does ("Structured content modeling guidance for schema design...") and when to use it via a concrete "Use this skill when designing or refactoring content types, deciding field shapes, debating reusable versus nested content..." trigger clause.	5 / 5
Trigger Term Quality	Natural terms users would say are present ("field shapes", "reusable versus nested content", "omnichannel content models", "page-shaped", "headless CMSes", "Sanity"), but a few common synonyms or file/extension-level terms are missing, fitting the 'good coverage, a few natural terms missing' anchor.	4 / 5
Distinctiveness Conflict Risk	The content-modeling / headless-CMS / Sanity niche is mostly distinct with clear triggers, but there is minor overlap risk with generic data-modeling or CMS skills.	4 / 5
	Total	17 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: sanity-io/agent-toolkit
Path: skills/content-modeling-best-practices/SKILL.md
Commit: 88d6cdf

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.