Back to Skills

sanity-schema-manager

verified

Manages schema lifecycle including scaffolding, safe field deprecation, and data migrations. Use when modifying existing schemas.

View on GitHub

Marketplace

sanity-agent-toolkit

sanity-io/agent-toolkit

Plugin

sanity-plugin

Repository
Verified Org

sanity-io/agent-toolkit
55stars

sanity-plugin/skills/sanity-schema-manager/SKILL.md

Last Verified

January 14, 2026

Install Skill

Select agents to install to:

Scope:
npx add-skill https://github.com/sanity-io/agent-toolkit/blob/main/sanity-plugin/skills/sanity-schema-manager/SKILL.md -a claude-code --skill sanity-schema-manager

Installation paths:

Claude
.claude/skills/sanity-schema-manager/
Powered by add-skill CLI

Instructions

# Schema Manager

This skill handles the lifecycle of Sanity Schema types.

## Procedure

1.  **Scaffold (Create)**
    *   Use templates to create `document`, `object`, or `singleton` types.
    *   **Constraint:** Ensure `defineType` and `defineField` are used.
    *   **Constraint:** Ensure an icon is imported from `@sanity/icons`.

2.  **Deprecate (Update)**
    *   Ask: "Which field do you want to deprecate?"
    *   **Action:** Apply the "ReadOnly -> Hidden -> Deprecated" pattern to the field definition.
    *   **Output:**
        ```typescript
        defineField({
          name: 'oldField',
          deprecated: { reason: 'Use newField instead' },
          readOnly: true,
          hidden: ({value}) => value === undefined,
          initialValue: undefined
        })
        ```

3.  **Migrate (Data)**
    *   Generate a migration script using `@sanity/migrate` or standard client patches.
    *   **Template:** Iterate over documents -> `patch(doc.id).set({ newField: doc.oldField }).unset(['oldField'])`.

4.  **Clean (Delete)**
    *   Only allow deleting a field definition if the user confirms "I have migrated the data and the field is undefined in all documents."

Validation Details

Front Matter
Required Fields
Valid Name Format
Valid Description
Has Sections
Allowed Tools
Instruction Length:
1047 chars