Sanity CMS Skill

intent

publish documents to any Sanity CMS instance via the Content API. use this when a user asks you to create a draft, push a document, upload an image asset, or convert content into Sanity format. works with any schema and document type (blog posts, pages, products, authors, etc.). the skill handles schema discovery, JSON formatting, image uploads, and draft creation in one workflow.

inputs

environment variables (required):

• SANITY_PROJECT_ID: your Sanity project ID (string, no default)
• SANITY_API_TOKEN: write-enabled API token (Editor role minimum; no default)

environment variables (optional):

• SANITY_DATASET: target dataset name (default: production)
• COVER_IMAGE_FIELD: field name for cover/hero images (default: coverImage)
• DRAFT_PREFIX: create draft or publish live (default: true for drafts; set false to publish immediately)

external connections:

• Sanity CMS API endpoint (authenticated via SANITY_API_TOKEN)
• web_fetch for remote schema URLs (GitHub raw links, etc.)

files and paths:

• <skill-dir>/scripts/publish_draft.sh: the publish script (resolve path relative to skill installation)
• references/api.md: API patterns (upload, mutate, query, schema introspection, GROQ)
• references/portable-text.md: block field formatting guide

procedure

step 1: obtain the target schema (try in order)

1a. Check workspace for schema file at a known path (e.g. sanity-schemas/blogPost.ts). read it directly if present.

1b. Schema pasted in chat? Parse the TypeScript or JavaScript from the conversation.

1c. User shares a remote URL (GitHub raw, etc.). fetch it with web_fetch and parse the result.

1d. No schema file or URL available? Query the Sanity dataset directly using schema introspection (see references/api.md section "Schema Introspection"). use array::unique(*[]._type) to discover document types, then fetch one sample document to infer field names and shapes.

output from step 1: schema object with field definitions (types, validation rules, required fields).

step 2: understand field requirements from schema

2a. For any array field with type: 'block', the body must be Portable Text format (see references/portable-text.md).

2b. For any reference field (categories, authors, tags, etc.), query the target dataset via GROQ to get valid document IDs (see references/api.md section "GROQ queries"). do not invent reference IDs.

2c. Identify all required fields. note any validation constraints (min/max length, enum values, etc.).

output from step 2: field requirements checklist (which fields are required, which need Portable Text, which need reference lookups).

step 3: build the document JSON

3a. create a JSON object matching the schema. omit _id (the script generates a drafts. prefixed UUID). omit the cover image field (the script injects it after upload).

3b. populate all required fields. respect validation constraints (length, enum, etc.).

3c. save the JSON to a logical workspace path (e.g. brain/projects/<slug>-sanity.json).

output from step 3: valid document JSON file at a known path.

step 4: run the publish script

4a. resolve the script path relative to skill installation (e.g. ~/.openclaw/skills/sanity-cms/scripts/publish_draft.sh or <workspace>/skills/sanity-cms/scripts/publish_draft.sh).

4b. execute the script with the document JSON path and optional cover image path:

bash <skill-dir>/scripts/publish_draft.sh \
  path/to/document.json \
  path/to/cover-image.png

4c. if using optional env overrides (dataset, field names, draft vs. live):

SANITY_DATASET=staging COVER_IMAGE_FIELD=mainImage DRAFT_PREFIX=false \
  bash <skill-dir>/scripts/publish_draft.sh doc.json cover.jpg

output from step 4: script prints the draft document ID and success/error messages to stdout.

step 5: report results to user

5a. extract the draft ID from script output.

5b. report back: the draft document ID, a clickable Sanity Studio link (ask user for Studio URL if unsure), and any fields that still need manual attention (unpopulated references, etc.).

output from step 5: user confirmation message with actionable next steps.

decision points

if user provides a schema file: read and parse it locally (step 1a). proceed to step 2.

else if user pastes schema in chat: extract and parse from conversation (step 1b). proceed to step 2.

else if user provides a remote schema URL: fetch with web_fetch, parse result (step 1c). proceed to step 2.

else if no schema is available: use schema introspection API query (step 1d). proceed to step 2.

if the schema has reference fields: query the Sanity dataset via GROQ to fetch valid document IDs before building the JSON (step 2b). do not proceed to step 3 until references are resolved.

if the schema has block (array) fields: format the body using Portable Text syntax (step 2a). do not use plain text.

if the user wants to publish live immediately: set DRAFT_PREFIX=false in step 4c. otherwise, always create a draft first (default behavior).

if the schema has no image field: omit the cover image argument in step 4b. the script still succeeds.

if the script returns an error (auth, network, validation): report the error to user. do not retry silently. common causes: expired SANITY_API_TOKEN, wrong SANITY_PROJECT_ID, network timeout, or malformed JSON. ask user to verify env vars or check network.

if the script returns a draft ID: proceed to step 5. if no draft ID in output, treat as failure and report error.

output contract

on success:

• draft document created in Sanity dataset (with drafts. prefix in document ID)
• cover image uploaded and linked (if provided and schema has image field)
• script output includes the draft document ID (format: drafts.<uuid>)
• no data loss or partial uploads (all-or-nothing transaction)

file outputs:

• document JSON saved to workspace path (e.g. brain/projects/<slug>-sanity.json)
• cover image uploaded to Sanity asset store (URL returned by script)

error outputs:

• script returns non-zero exit code if JSON validation fails, auth fails, network times out, or API rejects the document
• error message includes reason (e.g. "missing required field: title", "invalid token", "timeout after 30s")

outcome signal

user sees:

• draft document ID printed to terminal (e.g. drafts.abc123def456)
• confirmation message: "draft created successfully" or similar
• clickable link to Sanity Studio with the draft ID
• (optional) list of fields needing manual attention before publishing

user can open Sanity Studio, navigate to the draft, and verify content looks correct.

---

credits: original skill by clawhub. enriched to Implexa standards.