Introducing: Sanity Agent Skills

Written by Jon Eide Johnsen

Sanity is a flexible platform with a lot of depth. AI agents are great at writing Sanity code that works, but that flexibility means there are often multiple ways to do things — and agents don't always pick the optimal approach. A GROQ query might work but fetch more data than you need. A studio might miss Visual Editing configuration. Portable Text might render without proper custom components.

Today we're releasing Agent Skills for Sanity – a collection of best practices that teach your AI agent how to build with Sanity correctly.

What's inside

We've packaged the collective experience from Sanity's engineering, support, and customer solutions teams into four skill packages:

The Sanity skill alone contains 25+ rules across 10 categories. Each rule follows a consistent format: explain the problem, show the wrong way, show the right way.

For example, the skill can help your coding agent to:

• Optimize slow GROQ queries: Rules like "Avoid Joins in Filters" teach agents to use _ref comparisons instead of -> in filter expressions – a common mistake that doesn't surface until your dataset grows
• Set up Visual Editing correctly: Agents learn to configure studioUrl, strip out stega strings from OpenGraph image content, and wire up the Presentation tool
• Build page builders that scale: When to use inline objects vs. references, how to structure preview configurations, proper array key handling
• Handle Portable Text properly: Custom component patterns, link rendering, and avoiding common serialization mistakes
• Write safe migrations: Using defineMigration from sanity/migrate instead of raw client patches, with idempotent filter patterns

How agents use these rules

This repo follows the Agent Skills format – an open standard for packaging knowledge for AI agents. The format works with Claude Code, Cursor, GitHub Copilot, VS Code, Codex, OpenCode, and several other AI development tools.

Agent Skills are folders of instructions and examples that agents discover and reference on demand. Think of them as documentation written for machines. Instead of hoping an agent learned the right patterns from training data, you give it explicit rules to follow.

When you install the skill, your agent gets all the rules. It references them when writing GROQ queries, creating schemas, or setting up Visual Editing. The agent treats the rules as the source of truth rather than improvising.

Why we built this

Our support team answers the same questions weekly. Our solutions engineers see the same schema mistakes across projects. Our docs contain this knowledge, but agents don't always find the right page at the right time.

Common issues we see:

• GROQ queries that work but don't scale
• Schemas missing hotspot on images (cropping breaks)
• Page builders using references when objects would be simpler
• Visual Editing setups missing studioUrl or proper stega cleaning
• Array items without stable _key values
• Field deletions that orphan production data

We packaged what we know into a format agents can use directly. Now when you ask your agent to "add a page builder to my schema," it knows to use inline objects for content blocks, add preview configuration, and set up proper array validation.

Beyond Sanity-specific patterns

Content modeling, SEO, and experimentation aren't Sanity-specific – but they're areas where agents often miss the mark. We included best practices for:

• Content modeling: Why your blueHighlightBox field name will haunt you when design changes. How to separate content from presentation. When to use references vs. embedding.
• SEO and AEO: What actually moves Core Web Vitals (LCP, INP, CLS). How to structure content for AI answer engines. EEAT signals that matter.
• Content experimentation: Running A/B tests on content without code deploys. Personalization patterns that don't create maintenance nightmares.

These skills have Sanity-specific implementation notes where relevant, but the principles apply broadly.

How this fits with the Sanity MCP server

If you're using the Sanity MCP server, your agent can already create and deploy schemas, as well as querying, creating and updating content. The MCP server also exposes a set of agent rules through the list_sanity_rules and get_sanity_rules tools.

Agent skills work slightly differently. They're portable packages that live in your codebase and work across any tool that supports the Agent Skills standard. The agent sees available skills and loads them when relevant to the task – no server connection needed.

Use MCP when you need your agent to interact with your Sanity projects. Use skills when you want best practices that travel with your repo.

Get started

The repo is live at github.com/sanity-io/agent-toolkit.

Install with Vercel's skills CLI: