# Agent Skills

**DatoCMS Skills** are expert playbooks that AI coding assistants load on demand. Without them, an AI can call DatoCMS APIs, but will guess at conventions, pick wrong field types, and miss integration patterns. With them, **agents work like a senior DatoCMS developer**: correct GraphQL queries, solid content modeling, idiomatic frontend integrations, clean migrations, and well-structured plugins — on the first try.

> [!PROTIP] Pro tip: Skills or MCP?
> -   **Working in a local repo?** Install Agent Skills — **they're all you need**. Every MCP capability is already built in via local CLI calls, plus all the expertise MCP can't carry: content modeling best practices, frontend integration patterns, migration workflows, plugin conventions, and more.
>     
> -   **No local terminal?** (web, mobile, chat apps) Use the [**MCP server**](https://www.datocms.com/docs/mcp-server.md) instead.
>     
> 
> Pick one, not both.

## What you can do

Most skills trigger automatically based on your prompt.

###### Building with DatoCMS

-   **Content modeling** — schema-design decisions: model vs block, references vs embedded blocks, taxonomies, field shapes, validators, editor appearances.
-   **Reading content** — GraphQL queries against the Content Delivery API: filters, pagination, localization, modular content, Structured Text, responsive images, SEO metadata, typed queries with gql.tada or codegen.
    
-   **Writing content & automation** — programmatic CMA scripts: record CRUD, bulk imports/exports, asset uploads, environment forks and promotions, webhooks, roles and tokens, scheduled publishing, audit logs.
-   **CLI workflows** — migrations, schema-type generation, typed CMA scripts, environment operations, CI/CD pipelines, WordPress/Contentful imports.
    
-   **Frontend integrations** — draft mode, Web Previews, Visual Editing, Content Link overlays, real-time preview subscriptions, cache-tag invalidation, SEO/sitemap wiring across Next.js App Router, Nuxt, SvelteKit, Astro, plus `react-datocms`, `vue-datocms`, `@datocms/svelte`, and `@datocms/astro`.
    

###### Building DatoCMS plugins

-   **Plugin scaffolding** — create a brand-new plugin from scratch with the Vite/React structure, picking the initial surfaces (field extensions, config screens, sidebars, pages, asset sources).
-   **Plugin maintenance** — patch and extend an existing plugin: hook additions, field extension tweaks, sidebar/page changes, validation updates.
    
-   **Plugin design system** — restyle plugin UI to feel native to the DatoCMS dashboard — config screens, panels, modals, forms, density and spacing.
    

## Installation

Pick the install method for your agent. Every installer brings the full set by default — the skills are cross-linked and meant to work together.

###### Claude Code

Claude Code's native plugin system bundles all DatoCMS skills with auto-update support and namespaced invocation:

Terminal window

```bash
/plugin marketplace add datocms/agent-skills
/plugin install datocms@datocms-skills
```

All skills install; the right one activates based on your prompt. Auto-update from `/plugin` → **Marketplaces** → `datocms-skills`.

###### Codex

Codex also supports installing through its plugin marketplace. Add the DatoCMS marketplace once, then install the plugin from the Codex plugin picker inside a session:

Terminal window

```bash
codex plugin marketplace add datocms/agent-skills
```

Then open a Codex session and install from the plugin picker:

Terminal window

```bash
/plugins
```

Choose **DatoCMS** and "Install plugin"

###### Cursor, Windsurf, GitHub Copilot, and other agents

The universal `npx skills` installer brings the full set:

Terminal window

```bash
npx skills add datocms/agent-skills
```

Add `-a <agent>` to target a specific agent (e.g. `-a cursor`), `-g` to install globally instead of per-project, and `-y` to skip confirmation prompts. Multi-agent install in one shot:

Terminal window

```bash
npx skills add datocms/agent-skills -a claude-code -a codex -a cursor -y
```

###### Claude.ai (web)

On the web you can't run CLI commands or edit local files, so most development-focused skills don't apply. The ones worth uploading are [`datocms-content-modeling.zip`](https://github.com/datocms/agent-skills/raw/master/zips/datocms-content-modeling.zip) (content modeling) and [`datocms-cma.zip`](https://github.com/datocms/agent-skills/raw/master/zips/datocms-cma.zip) (writing content & automation) — best paired with the [DatoCMS MCP server](https://www.datocms.com/docs/mcp-server.md), which lets the agent read and update your project directly from the conversation.

Upload the .zip files via **Customize → Skills** → **+** → **Upload a skill**.

## Usage

###### Automatic skills

Most skills activate automatically. Describe your task in plain language and the right skill picks it up:

-   "Should testimonials be a model or a block?"
-   "Write a GraphQL query to fetch all blog posts with images"
    
-   "How do I paginate past the 100-record limit?"
-   "Add draft mode to my Next.js app"
    
-   "Why isn't my Visual Editing overlay showing up?"
-   "Create a migration that adds a `category` field to the blog\_post model"
    
-   "Bulk-publish all draft records of type `article`"
-   "Import this CSV into the authors model"
    
-   "Make my plugin config screen match the DatoCMS style"
-   "Create a new DatoCMS plugin from scratch"
    

###### The setup skill (explicit)

`datocms-setup` is the one skill you invoke explicitly. It handles end-to-end project bootstrapping — draft mode, visual editing, migrations workflows, content imports — and queues prerequisites automatically when needed.

-   **Claude Code** — `/datocms-setup <your request>`
-   **Codex** — `$datocms-setup <your request>`
    

Phrase prompts as the outcome you want:

```text
/datocms-setup install visual editing in this project
/datocms-setup set up draft mode and web previews
/datocms-setup add migrations and a release workflow
```

## How it works

Unlike a raw API integration, Skills package not just *what* DatoCMS exposes but *how* to use it well — so the agent gets your task right on the first try.

###### Description-based routing

Each skill ships with a description. When you describe a task, the agent inspects all installed skill descriptions and loads the most relevant one into context. You don't call skills explicitly — they activate themselves.

###### Local files, your control

Skills are markdown plus a few helper assets, stored on disk in `.agents/skills/` (universal) or per-agent dirs like `~/.claude/skills/` and `~/.codex/skills/`. They're inspectable, version-controllable, and removable at any time.

###### Cross-skill references

Skills hand off to each other. The setup skill might queue a migration via the CLI skill, which in turn types its TypeScript helpers via the CMA skill. Installing a single skill in isolation breaks these handoffs — that's why every installer brings the full set by default.

## Security

Skills run with the **full permissions of the host agent**. They can read and write files, run shell commands, and make network requests on your behalf. That power is useful, but it's also worth knowing.

-   All DatoCMS skills are open source and visible at [github.com/datocms/agent-skills](https://github.com/datocms/agent-skills). Inspect the markdown before granting an agent access to a sensitive repo.
-   The `npx skills` installer surfaces automated security scans (Gen / Socket / Snyk) alongside each skill at install time.