DatoCMS Agent Skill

This skill provides comprehensive guidance for working with DatoCMS, a headless CMS platform. It combines decision frameworks, executable workflows, and complete documentation reference.

When to Use This Skill

Use this skill when:

Building or maintaining a DatoCMS project
Integrating DatoCMS with frameworks (Next.js, React, Vue, etc.)
Managing content models, records, or assets via API
Setting up webhooks or real-time updates
Working with DatoCMS plugins or the Plugin SDK
Migrating content or managing multiple environments
Troubleshooting DatoCMS API or integration issues

Do NOT use this skill for:

Generic CMS comparisons (unless DatoCMS-specific)
Non-DatoCMS headless CMS implementations
Basic frontend development unrelated to DatoCMS

API Decision Guide

DatoCMS provides multiple APIs for different use cases:

Content Delivery API (CDA)

Use for: Fetching published content for production sites

GraphQL-based, read-only
Optimized for speed with global CDN
Supports filtering, sorting, pagination
Best for: SSR, SSG, client-side fetching

Example:

import { executeQuery } from '@datocms/cda-client';

const result = await executeQuery(query, {
  token: process.env.DATOCMS_API_TOKEN,
  environment: 'main'
});

Content Management API (CMA)

Use for: Creating, updating, deleting content and schema

REST-based with full CRUD operations
Requires write permissions
Best for: Admin panels, migrations, automated content creation

Example:

import { buildClient } from '@datocms/cma-client-node';

const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

// Create a record
const record = await client.items.create({
  item_type: { type: 'item_type', id: 'blog_post' },
  title: 'New Post',
  content: 'Content here'
});

Asset API

Use for: Uploading files and managing assets

Two-step process: request upload URL, then upload file
Supports images, videos, documents

Real-Time Updates API

Use for: Live preview, collaborative editing

WebSocket-based
Reflects draft changes instantly

Getting Started

1. API Tokens

Go to Settings > API Tokens in your DatoCMS project
Read-only token for CDA (can be public)
Full-access token for CMA (keep secret)

2. Install Clients

# For content fetching
npm install @datocms/cda-client

# For content management
npm install @datocms/cma-client-node

# For React/Next.js
npm install react-datocms

3. Basic Query

import { executeQuery } from '@datocms/cda-client';

const query = `
  query {
    allBlogPosts {
      id
      title
      slug
      publishedAt
    }
  }
`;

const data = await executeQuery(query, {
  token: process.env.DATOCMS_API_TOKEN
});

Workflow Playbooks

1. Schema Management: Create Models & Fields

When: Setting up new content types or modifying existing ones

import { buildClient } from '@datocms/cma-client-node';

const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

// Create a model
const model = await client.itemTypes.create({
  name: 'Blog Post',
  api_key: 'blog_post',
  singleton: false
});

// Add fields
await client.fields.create(model.id, {
  label: 'Title',
  field_type: 'string',
  api_key: 'title',
  validators: { required: {} }
});

await client.fields.create(model.id, {
  label: 'Content',
  field_type: 'structured_text',
  api_key: 'content'
});

2. Content Operations: CRUD + Publishing

When: Managing content records programmatically

// Create draft
const draft = await client.items.create({
  item_type: { type: 'item_type', id: 'blog_post' },
  title: 'My Post',
  content: { /* DAST structure */ }
});

// Update
await client.items.update(draft.id, {
  title: 'Updated Title'
});

// Publish
await client.items.publish(draft.id);

// Unpublish
await client.items.unpublish(draft.id);

// Delete
await client.items.destroy(draft.id);

3. Asset Uploads: Two-Step Flow

When: Uploading images, videos, or documents

import { buildClient } from '@datocms/cma-client-node';
import fs from 'fs';

const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });

// Step 1: Create upload request
const path = './image.jpg';
const uploadRequest = await client.uploads.createFromFileOrBlob({
  fileOrBlob: fs.createReadStream(path),
  filename: 'image.jpg'
});

// Step 2: Use upload in a record
await client.items.create({
  item_type: { type: 'item_type', id: 'blog_post' },
  title: 'Post with Image',
  cover_image: {
    upload_id: uploadRequest.id
  }
});

4. Migrations: Sandbox to Production

When: Testing schema changes before deploying

# Create sandbox environment
# (Do this in DatoCMS UI: Settings > Environments)

# Make changes in sandbox
DATOCMS_ENVIRONMENT=sandbox node update-schema.js

# Test in sandbox
# Preview at: https://your-project.admin.datocms.com/editor?environment=sandbox

# Promote to primary environment (via UI or API)

5. Structured Text (DAST): Handling Rich Content

When: Working with rich text fields

import { render } from 'datocms-structured-text-to-html-string';

// DAST structure
const structuredText = {
  schema: 'dast',
  document: {
    type: 'root',
    children: [
      {
        type: 'heading',
        level: 1,
        children: [{ type: 'span', value: 'Hello World' }]
      },
      {
        type: 'paragraph',
        children: [
          { type: 'span', value: 'This is ' },
          { type: 'span', marks: ['strong'], value: 'bold text' }
        ]
      }
    ]
  }
};

// Render to HTML
const html = render(structuredText);

6. Webhooks: Event Notifications

When: Triggering builds or syncing data on content changes

// Create webhook via CMA
const webhook = await client.webhooks.create({
  name: 'Deploy on Publish',
  url: 'https://api.vercel.com/v1/integrations/deploy/...',
  events: [
    { entity_type: 'item', event_types: ['publish', 'unpublish'] }
  ],
  http_basic_user: 'user',
  http_basic_password: 'pass'
});

7. Framework Integration: Next.js Example

When: Building a Next.js site with DatoCMS

// app/blog/page.tsx
import { executeQuery } from '@datocms/cda-client';

const query = `
  query {
    allBlogPosts(orderBy: publishedAt_DESC) {
      id
      title
      slug
      excerpt
    }
  }
`;

export default async function BlogPage() {
  const { allBlogPosts } = await executeQuery(query, {
    token: process.env.DATOCMS_API_TOKEN!
  });

  return (
    <div>
      {allBlogPosts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </div>
  );
}

MCP Server Integration

DatoCMS provides an official Model Context Protocol (MCP) server for AI agents:

Installation

{
  "mcpServers": {
    "datocms": {
      "command": "npx",
      "args": ["-y", "@datocms/mcp-server"],
      "env": {
        "DATOCMS_API_TOKEN": "your-full-access-token"
      }
    }
  }
}

Available Tools

list_models - List all content models
get_model - Get model details with fields
list_records - List records of a model
get_record - Get single record by ID
create_record - Create new record
update_record - Update existing record
delete_record - Delete record

Troubleshooting

Common Issues

1. "Invalid API token"

Verify token in Settings > API Tokens
Check environment variable is loaded
Ensure token has required permissions (read-only vs full-access)

2. "Model/Field not found"

Use api_key not id in queries
Check model exists in current environment
Verify field spelling and case sensitivity

3. "Rate limit exceeded"

CDA: 30 requests/second (burst: 60)
CMA: 15 requests/second
Implement exponential backoff

4. Asset upload fails

Check file size limits (5GB max)
Verify file type is supported
Use createFromFileOrBlob method

5. Structured text not rendering

Validate DAST schema structure
Use official rendering packages
Check for custom block types

Debug Checklist

API token is correct and has required permissions
Environment name matches (main vs sandbox)
API key names match schema (not display names)
Request payload matches API documentation
Check DatoCMS status page for outages
Review API logs in DatoCMS settings

Documentation Reference

Below is the complete index of DatoCMS documentation organized by topic. All links point to Markdown versions for easy parsing.

datocms

Safety Notice

Copy this and send it to your AI assistant to learn