skills/sanity-io__agent-toolkit
1
0
Fork 0
mirror of https://github.com/sanity-io/agent-toolkit.git synced 2026-09-14 18:39:20 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
add-angular-guide
sanity-io__agent-toolkit/AGENTS.md
T
James Woods 17f7b5b428 fix: deduplicate atomic references into comprehensive guides 
Delete 25 atomic reference files that duplicated content already
covered by the comprehensive topic guides (groq.md, schema.md, etc.).
Unique content from atomics (optimizable filters table, defineMigration
example, compound cursor pattern, icon mapping table, stegaClean
alternatives, etc.) was merged into the corresponding guide before
deletion.

Also makes migration.md an index that points to migration-html-import.md
for the HTML deep-dive, keeping the pattern extensible for future
migration guides.

Updates SKILL.md and AGENTS.md to reflect the consolidated structure
(47 → 22 reference files).
2026-02-24 12:03:17 +00:00

143 lines
8.0 KiB
Markdown
Raw Permalink Blame History

# 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](https://github.com/sanity-io/agent-toolkit#option-3-install-plugin).
## Commands
```bash
# 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 reference files.
> For the full reference index, see `skills/sanity-best-practices/SKILL.md`.
| Topic | Trigger Keywords | Reference |
| :--- | :--- | :--- |
| **Onboarding** | `start`, `setup`, `init`, `new project` | `skills/sanity-best-practices/references/get-started.md` |
| **Project Structure** | `structure`, `monorepo`, `embedded studio`, `file naming` | `skills/sanity-best-practices/references/project-structure.md` |
| **Schema** | `schema`, `model`, `document`, `field`, `defineType` | `skills/sanity-best-practices/references/schema.md` |
| **Deprecation** | `deprecate`, `remove field`, `legacy`, `migration` | `skills/sanity-best-practices/references/schema.md` |
| **Import/Migration** | `import`, `wordpress`, `html`, `markdown`, `migrate` | `skills/sanity-best-practices/references/migration.md` |
| **Next.js** | `next.js`, `app router`, `server component`, `fetch` | `skills/sanity-best-practices/references/nextjs.md` |
| **Nuxt** | `nuxt`, `vue`, `nuxt.js` | `skills/sanity-best-practices/references/nuxt.md` |
| **Astro** | `astro`, `islands` | `skills/sanity-best-practices/references/astro.md` |
| **Remix/React Router** | `remix`, `react router`, `loader` | `skills/sanity-best-practices/references/remix.md` |
| **Svelte** | `svelte`, `sveltekit`, `kit` | `skills/sanity-best-practices/references/svelte.md` |
| **Visual Editing** | `stega`, `visual editing`, `clean`, `overlay`, `presentation`, `usePresentationQuery` | `skills/sanity-best-practices/references/visual-editing.md` |
| **Page Builder** | `page builder`, `pageBuilder`, `block component`, `alignment`, `switch render` | `skills/sanity-best-practices/references/page-builder.md` |
| **Rich Text** | `portable text`, `rich text`, `block content`, `serializer`, `PTE`, `marks`, `annotations` | `skills/sanity-best-practices/references/portable-text.md` |
| **Images** | `image`, `urlFor`, `crop`, `hotspot`, `lqip` | `skills/sanity-best-practices/references/image.md` |
| **Studio Structure** | `structure`, `desk`, `sidebar`, `singleton`, `grouping` | `skills/sanity-best-practices/references/studio-structure.md` |
| **Localization** | `i18n`, `translation`, `localization`, `language`, `multilingual`, `localized singleton` | `skills/sanity-best-practices/references/localization.md` |
| **SEO** | `seo`, `metadata`, `sitemap`, `og image`, `open graph`, `json-ld`, `redirect` | `skills/sanity-best-practices/references/seo.md` |
| **Shopify/Hydrogen** | `shopify`, `hydrogen`, `e-commerce`, `storefront`, `sanity connect` | `skills/sanity-best-practices/references/hydrogen.md` |
| **GROQ** | `groq`, `query`, `defineQuery`, `projection`, `filter`, `order` | `skills/sanity-best-practices/references/groq.md` |
| **TypeGen** | `typegen`, `typescript`, `types`, `infer`, `satisfies`, `type generation` | `skills/sanity-best-practices/references/typegen.md` |
| **App SDK** | `app sdk`, `custom app`, `useDocuments`, `useDocument`, `DocumentHandle`, `SanityApp`, `sdk-react` | `skills/sanity-best-practices/references/app-sdk.md` |
| **Blueprints** | `blueprints`, `IaC`, `infrastructure`, `stack`, `defineBlueprint` | `skills/sanity-best-practices/references/blueprints.md` |
### Using the Knowledge Router
**Before modifying any code:**
1. Identify which topics from the table above apply to your task
2. Read the corresponding reference file(s) using the file path
3. Follow the patterns and constraints defined in those references
Example: If asked to "create a blog post schema", read `skills/sanity-best-practices/references/schema.md` 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 reference 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.
Reference in New Issue View Git Blame Copy Permalink