前言¶
用 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
