前言¶
用 Headless CMS 做内容站时，常见难点不在「能不能接 API」，而在 schema 怎么建模、GROQ 怎么写才稳、TypeGen 和前端类型怎么对齐、Visual Editing 和框架集成又该按哪套文档走。让 AI 直接改 Sanity 代码时，它容易沿用过期示例、自己造 document _id，或在 file 字段里塞生产级视频——这些都会变成线上账单或维护成本。
下面介绍 Sanity 官方在 Sanity Agent Toolkit 里维护的 sanity-best-practices Skill：把 schema、GROQ、TypeGen、Visual Editing、框架集成等内容工作流相关的约定和分主题参考文档，整理成 Agent 可按任务加载的说明，减少上述偏差。
这是什么¶
sanity-best-practices 是 Sanity 团队维护的 Agent Skill，面向 schema 设计、GROQ 查询、TypeGen、Visual Editing、图片与 Portable Text、Studio 结构、本地化、迁移、Sanity Functions、webhooks、Blueprints，以及 Next.js、Nuxt、Astro、Remix、SvelteKit、Angular、Hydrogen、App SDK、Dashboard 内 Studio（defineApplication）等集成场景。
Skill 本体在仓库路径 skills/sanity-best-practices；与 MCP 直连项目、其他 Skill 或插件打包安装不同，它侧重「按任务读指南 + 对错示例」，适合在写 schema、查 GROQ、搭预览或审 Sanity 代码库时让 Agent 先对齐官方做法。
官方说明里写明：涉及 defineType / defineField、defineQuery、内容建模、Presentation / 预览、前端集成、documentEventHandler、defineDocumentFunction、@sanity/functions、@sanity/blueprints、sanity.blueprint.ts 等关键词时，应优先引用本 Skill。
核心功能¶
适用时机（When to Apply）¶
资料中列出的典型场景包括：
- 新建 Sanity 项目或团队 onboarding
- 与前端框架集成（Next.js、Nuxt、Astro、Remix、SvelteKit、Hydrogen 等）
- 编写或优化 GROQ
- 设计内容 schema
- 实现 Visual Editing 与 live preview
- 图片、Portable Text、页面构建器（page builder）
- 配置 Studio structure、TypeGen、本地化
- 从其他系统迁移内容
- 使用 Sanity App SDK 做自定义应用
- 在 Sanity Dashboard 中开发或部署 Studio / 应用
- 用 Blueprints 管理基础设施
- 用 Sanity Functions 或 webhooks 做内容自动化
全局规则（Global Rules）¶
Skill 在跨主题前先强调几条硬约定，例如：
- 普通文档让 Sanity 生成
_id，不要自建确定性 UUID、由 slug 推导的 ID 或遗留系统 ID。 - 用
reference建模关系，再用 GROQ lookup、source-key 字段或创建接口返回的_id解析关联文档。 - 显式 document ID 主要用于由 Studio Structure 控制的单例（含本地化单例，如
homePage-en）。
视频与资产¶
生产环境不要用 Sanity file 资产做大规模视频播放：file 以原始下载交付，无转码与自适应流，流量易导致高额带宽账单。Enterprise 且开通 video add-on 时，资料建议用 Sanity Media Library（经 Mux 转码与自适应流），字段用 sanity/media-library 的 defineVideoField()，播放用 @mux/mux-player-react 与资产的 playback ID。其他方案包括 Studio 侧 sanity-plugin-mux-input，或 YouTube / Vimeo 仅存 embed URL。短预览类小文件可放在 file 字段，面向用户的大规模视频须走 Media Library 或专用流媒体服务。
快速参考：集成与主题¶
Skill 采用「只加载与当前任务相关的 1～2 个参考文件」的设计。集成类指南包括：get-started、nextjs、nuxt、angular、astro、remix、svelte、hydrogen、project-structure、app-sdk、dashboard、blueprints、functions。
主题类指南包括：groq、schema、visual-editing、page-builder、portable-text、image、studio-structure、typegen、seo、localization、migration、migration-html-import。
每个参考文件（如 references/groq.md、references/schema.md、references/nextjs.md）通常包含：该主题的完整说明、错误与正确代码对照、决策矩阵与工作流说明，以及框架相关模式。
Toolkit 层面还提到：整套 Agent 资源包含约 25 个集成/主题指南与 26 条聚焦的最佳实践规则（以仓库当前说明为准）。
安装与启用¶
本 Skill 属于 sanity-io/agent-toolkit。安装方式与你是否同时要 MCP、插件有关。
仅安装 Agent Skills（含 sanity-best-practices）¶
适用于 Cursor、Claude Code 等兼容 Agent Skills 的客户端：
npx skills add sanity-io/agent-toolkit
安装的是 toolkit 中的 Skill 集合；sanity-best-practices 为其中之一。可用 npx skills list 查看已安装项，npx skills update 升级。
与 MCP、插件的关系（可选）¶
若希望 Agent 直接访问 Sanity 项目内容、数据集、schema 等，官方推荐 MCP，而非仅靠本地 Skill 文件：
npx sanity@latest mcp configure
该命令会为 Cursor、Claude Code、VS Code 等检测并配置 MCP；认证可走已登录的 Sanity CLI 用户。
Cursor 也可在 MCP 设置中手动添加 HTTP 服务：
{
"mcpServers": {
"Sanity": {
"type": "http",
"url": "https://mcp.sanity.io"
}
}
}
Codex 示例：
codex mcp add Sanity --url https://mcp.sanity.io
Claude Code 可通过官方插件市场安装 Sanity 插件（含 MCP、skills、命令），例如：
/plugin install sanity@claude-plugins-official
Cursor 用户也可从 Cursor Marketplace 的 Sanity 插件 一键安装同类能力。Skill 与 MCP 可并存：MCP 负责项目实况与规则同步，Skill 负责按主题加载长篇最佳实践。
手动拷贝（离线）¶
官方说明支持将 skill 参考文件拷贝到本地离线使用，但需自行跟进仓库更新。
典型用法¶
官方建议的工作流可以概括为三步：
- 选对入口：从与请求最匹配的一个框架或主题指南开始（例如只做 Next.js App Router + Live Content API，先读
nextjs；只优化查询，先读groq）。 - 按需扩展：任务跨域时再读第二份参考（例如 schema 变更后要改 TypeGen，再打开
typegen）。 - 对照示例改代码：在对应
references/*.md里按错误/正确示例和决策矩阵落地，而不是一次性加载全部 20+ 文件。
向 Agent 提需求时，尽量带上具体技术点，便于触发 Skill 描述中的范围，例如：
- 「按 sanity-best-practices 检查这份
defineField和 reference 用法」 - 「根据 Skill 里的 nextjs 参考，配置 Presentation / live preview」
- 「迁移 HTML 到 Portable Text，走 migration-html-import 里的 @portabletext/block-tools 流程」
适用场景与注意¶
适合谁：已经在用或准备用 Sanity 的全栈/前端团队；用 Cursor、Claude Code、Codex 等 Agent 写 schema、GROQ、框架集成或审 PR 的开发者。
优势：维护方是 Sanity 官方；主题覆盖从建模到 SEO、本地化、Functions、Blueprints；与 Agent Toolkit 里的 MCP、插件同源，便于和项目实况配合。
注意：
- Skill 是指令与参考文档，不会替代你在 Sanity 项目里的真实 schema 与数据集；敏感操作仍应走正常权限与 CI。
- 视频、
_id、reference 等有明确「不要做」的项，Agent 未加载本 Skill 时容易踩坑，复杂任务应显式要求遵循 sanity-best-practices。 - 仅装 Skill 时，内容更新依赖
npx skills update或重新add；MCP 侧规则可由服务端保持较新，二者可按需组合。
结尾¶
sanity-best-practices 把 Sanity 开发里分散在多份文档里的约定，收成可按任务加载的 Agent Skill：从 schema 与 GROQ 到 TypeGen、Visual Editing 和主流框架集成，并附带全局规则（如 document ID 与视频资产）以减少常见失误。
官方 Skill 目录：
https://github.com/sanity-io/agent-toolkit/tree/main/skills/sanity-best-practices
整套 Toolkit 安装与 MCP 说明：
https://github.com/sanity-io/agent-toolkit
