sanity-best-practices
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.
59
67%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/sanity-best-practices/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that thoroughly covers the Sanity ecosystem with highly specific capabilities, comprehensive trigger terms including API names and package references, and a clear 'Use this skill whenever...' clause. The only minor concern is the description's length, but the density of useful trigger terms justifies it. It uses proper third-person voice throughout.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description lists numerous specific domains and actions: schema design, GROQ queries, TypeGen, Visual Editing, images, Portable Text, Studio structure, localization, migrations, Sanity Functions, Blueprints, and multiple framework integrations. These are concrete, identifiable capabilities. | 3 / 3 |
Completeness | Clearly answers both 'what' (Sanity development best practices across many specific areas) and 'when' with an explicit 'Use this skill whenever...' clause listing detailed trigger conditions including specific function names, packages, and use cases like 'reviewing and fixing a Sanity codebase'. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms a developer would use: 'defineType', 'defineField', 'GROQ', 'defineQuery', 'content modeling', 'Presentation', '@sanity/functions', '@sanity/blueprints', 'sanity.blueprint.ts', plus framework names like 'Next.js', 'Nuxt', 'Astro', 'Remix', 'SvelteKit'. These are exactly the terms users would mention. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — the description is clearly scoped to the Sanity ecosystem with very specific package names, API references, and Sanity-specific terminology. It would be very unlikely to conflict with other skills unless another Sanity-specific skill existed. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill functions primarily as a table of contents or index file, pointing to external reference files for all substantive content. While the organization and progressive disclosure intent are reasonable, the body itself provides no actionable guidance—no code examples, no concrete commands, no decision matrices. The 'When to Apply' section is redundant with the quick reference list, and the mismatch between referenced file naming conventions (short names vs. 'references/groq.md' paths) creates confusion.
Suggestions
Add at least 2-3 concrete, executable code snippets for the most common tasks (e.g., a basic schema definition with defineType, a simple GROQ query with defineQuery) so the skill body itself provides immediate actionable value.
Remove or significantly condense the 'When to Apply' section since it largely duplicates the Quick Reference list—or merge them into a single decision table.
Clarify the actual file paths consistently: the quick reference uses short names like 'groq' and 'nextjs' while the 'How to Use' section references 'references/groq.md'—pick one convention and use it throughout.
Add a brief decision flowchart or 'start here' guidance with concrete conditions (e.g., 'If the user has an existing Next.js project, start with nextjs. If they're designing a new content model, start with schema.') to improve workflow clarity.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is reasonably organized but includes some unnecessary verbosity in the 'When to Apply' section that largely restates the quick reference table. The bullet lists are clean but the introductory framing could be tighter. | 2 / 3 |
Actionability | The skill body contains zero executable code, no concrete commands, and no specific examples. It is entirely a directory/index pointing to reference files, with no actionable guidance in the body itself—just descriptions of what each file covers. | 1 / 3 |
Workflow Clarity | There is a basic workflow suggestion ('Start with the single framework or topic guide that best matches the request, then read additional references only when the task crosses concerns'), but no sequenced steps, validation checkpoints, or decision logic for choosing between guides. | 2 / 3 |
Progressive Disclosure | The skill is structured as an index with clear one-level-deep references to topic and integration guides, which is good. However, no bundle files were provided to verify the referenced paths exist, and the reference file paths shown (references/groq.md, etc.) don't match the short names used in the quick reference list, creating ambiguity about actual file locations. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- sanity-io/agent-toolkit
- Commit
d7545f5
- Reviewed
Table of Contents
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.