sanity-io__agent-toolkit/AGENTS.md

Sanity Project

This is a Sanity-powered project. Use the Knowledge Router below to find Sanity guidance for your task. Available as a Claude Code and Cursor plugin.

Commands

# MCP Setup
npx sanity@latest mcp configure  # Configure MCP for your AI editor

# Schema & Types
npx sanity schema deploy     # Deploy schema to Content Lake (REQUIRED before MCP!)
npx sanity schema extract    # Extract schema for TypeGen
npx sanity typegen generate  # Generate TypeScript types

# Development
npx sanity dev               # Start Studio dev server
npx sanity build             # Build Studio for production
npx sanity deploy            # Deploy Studio to Sanity hosting

# Help
npx sanity docs search "query"  # Search Sanity documentation
npx sanity --help               # List all CLI commands

Knowledge Router

If the Sanity MCP server (https://mcp.sanity.io) is available, use list_sanity_rules and get_sanity_rules to load always up-to-date rules on demand. Otherwise, use the table below to find local rule files.

Topic	Trigger Keywords	Rule File
Project Structure	structure, monorepo, embedded studio, file naming	rules/sanity-project-structure.mdc
Onboarding	start, setup, init, new project	rules/sanity-get-started.mdc
Schema	schema, model, document, field, defineType	rules/sanity-schema.mdc
Deprecation	deprecate, remove field, legacy, migration	rules/sanity-schema.mdc
Import/Migration	import, wordpress, html, markdown, migrate	rules/sanity-migration.mdc
Next.js	next.js, app router, server component, fetch	rules/sanity-nextjs.mdc
Nuxt	nuxt, vue, nuxt.js	rules/sanity-nuxt.mdc
Astro	astro, islands	rules/sanity-astro.mdc
Remix/React Router	remix, react router, loader	rules/sanity-remix.mdc
Svelte	svelte, sveltekit, kit	rules/sanity-svelte.mdc
Visual Editing	stega, visual editing, clean, overlay, presentation, usePresentationQuery	rules/sanity-visual-editing.mdc
Page Builder	page builder, pageBuilder, block component, alignment, switch render	rules/sanity-page-builder.mdc
Rich Text	portable text, rich text, block content, serializer, PTE, marks, annotations	rules/sanity-portable-text.mdc
Images	image, urlFor, crop, hotspot, lqip	rules/sanity-image.mdc
Studio Structure	structure, desk, sidebar, singleton, grouping	rules/sanity-studio-structure.mdc
Localization	i18n, translation, localization, language, multilingual, localized singleton	rules/sanity-localization.mdc
SEO	seo, metadata, sitemap, og image, open graph, json-ld, redirect	rules/sanity-seo.mdc
Shopify/Hydrogen	shopify, hydrogen, e-commerce, storefront, sanity connect	rules/sanity-hydrogen.mdc
GROQ	groq, query, defineQuery, projection, filter, order	rules/sanity-groq.mdc
TypeGen	typegen, typescript, types, infer, satisfies, type generation	rules/sanity-typegen.mdc
App SDK	app sdk, custom app, useDocuments, useDocument, DocumentHandle, SanityApp, sdk-react	rules/sanity-app-sdk.mdc

Using the Knowledge Router

Before modifying any code:

1. Identify which topics from the table above apply to your task
2. Read the corresponding rule file(s) using the file path
3. Follow the patterns and constraints defined in those rules

Example: If asked to "create a blog post schema", read rules/sanity-schema.mdc first.

Agent Behavior

• Specialize in Structured Content, GROQ, and Sanity Studio configuration.
• Write best-practice, type-safe code using Sanity TypeGen.
• Build scalable content platforms, not just websites.
• Detect the user's framework from package.json and consult the appropriate rule file.

MCP Server (Preferred for Content Operations)

Prefer MCP tools over writing scripts for content operations:

Content Operations:

Tool	Use For
query_documents	Run GROQ queries
get_document	Fetch a single document by exact ID
create_documents_from_json	Create draft documents from JSON
create_documents_from_markdown	Create draft documents from markdown
patch_document_from_json	Apply precise modifications to document fields
patch_document_from_markdown	Patch a field using markdown content
publish_documents	Publish one or more drafts
unpublish_documents	Unpublish documents (move back to drafts)
discard_drafts	Discard drafts while keeping published documents

Schema & Development:

Tool	Use For
get_schema	Get full schema of the current workspace
list_workspace_schemas	List all available workspace schema names
deploy_schema	Deploy schema types to the cloud
search_docs / read_docs	Search and read Sanity documentation
list_sanity_rules / get_sanity_rules	Load best-practice development rules
migration_guide	Get guides for migrating from other CMSs

Media & AI:

Tool	Use For
generate_image	AI image generation for a document field
transform_image	AI transformation of an existing image

Releases:

Tool	Use For
create_version	Create a version document for a release
version_replace_document	Replace version contents from another document
version_discard	Discard document versions from a release
version_unpublish_document	Mark document to be unpublished when release runs

Project Management:

Tool	Use For
list_projects / list_organizations	List projects and organizations
create_project	Create a new Sanity project
list_datasets / create_dataset / update_dataset	Manage datasets
add_cors_origin	Add CORS origins for client-side requests
list_embeddings_indices / semantic_search	Semantic search on embeddings

Critical: After schema changes, deploy with deploy_schema before using content tools.

Boundaries

• Always:
  • Use defineQuery for all GROQ queries.
  • Prefer MCP tools for content operations (query, create, update, patch). For bulk migrations or when MCP is unavailable, NDJSON scripts are a valid alternative. Never use NDJSON scripts when MCP tools can accomplish the same task more simply.
  • Run deploy_schema after schema changes — required before using content tools. If a local Studio exists, update schema files first to keep them in sync with the deployed schema.
  • Follow the "Deprecation Pattern" when removing fields (ReadOnly -> Hidden -> Deprecated).
  • Run npm run typegen after schema or query changes (or enable automatic generation with typegen.enabled: true in sanity.cli.ts).
• Ask First:
  • Before modifying sanity.config.ts.
  • Before deleting any schema definition file.
• Never:
  • Hardcode API tokens (use process.env).
  • Use loose types (any) for Sanity content.