dotCMS Agent Toolkit

Agent skills and an MCP server for building and maintaining dotCMS sites — content types, pages, templates, containers, content placement, VTL, and headless Next.js. Works with Claude Code, Cursor, Codex, and any Agent Skills-compatible agent.

What's inside

Both support VTL-rendered and headless (Next.js) delivery.

Why a skill and not just docs: in dotCMS a missing piece renders blank or shell-only with HTTP 200, never an error. A successful response is not evidence that anything rendered. Every build path in these skills ends in a verify step for that reason.

Install

Skills — any agent

npx skills add dotCMS/agent-toolkit

Installs both skills. Add -g for all projects, --list to preview without installing, or --skill dotcms-best-practices for just one.

Plugin — Claude Code

Bundles the skills and the MCP server together.

/plugin marketplace add dotCMS/agent-toolkit
/plugin install dotcms@dotcms

Then /reload-plugins to activate without restarting.

Plugin — Cursor and Codex

The repo ships .cursor-plugin/ and .codex-plugin/ manifests. Point your client at this repository.

Agent Plugins

plugin.json and mcp.json conform to Agent Plugins 1.0.0. Any conforming client can install this repo directly.

MCP server

The plugin declares one server, dotcms, run over stdio:

{
  "mcpServers": {
    "dotcms": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@dotcms/mcp-server@latest"],
      "env": {
        "DOTCMS_URL": "https://your-instance.dotcms.com",
        "AUTH_TOKEN": "your-api-token"
      }
    }
  }
}

Export both before launching your client. The bundled .mcp.json reads ${DOTCMS_URL} and ${AUTH_TOKEN} from the environment, and Claude Code expands those only from the shell it was launched in. An unset variable is passed through as the literal string ${AUTH_TOKEN}, which comes back as a confusing 401 rather than a missing-configuration error.

The skills work without the MCP server — it makes the agent faster, not functional.

Contributing

npm install
npm run validate

That runs the same three checks CI does: skill frontmatter and manifest drift, the Claude Code manifests (claude plugin validate . --strict), and the Agent Plugins manifests against the published JSON schemas.

Adding a skill means a directory under skills/ with a SKILL.md whose name frontmatter equals the directory name, plus an entry in .claude-plugin/marketplace.json. validate:skills enforces both — npx skills add silently skips a skill with malformed frontmatter and still exits 0, so the check is what stops a broken skill shipping as a no-op.

The description field is the trigger contract: it decides whether an agent invokes the skill at all. State what it does and when to use it.

License

MIT — see LICENSE.

{
  "$schema": "https://www.schemastore.org/claude-code-marketplace.json",
  "name": "dotcms",
  "owner": {
    "name": "dotCMS",
    "email": "support@dotcms.com",
    "url": "https://www.dotcms.com"
  },
  "metadata": {
    "description": "dotCMS plugin for Claude Code — MCP server and agent skills for building and maintaining dotCMS sites.",
    "version": "0.1.0"
  },
  "plugins": [
    {
      "name": "dotcms",
      "displayName": "dotCMS",
      "source": "./",
      "description": "Build and maintain dotCMS sites — content types, pages, templates, containers, VTL, and headless Next.js.",
      "version": "0.1.0",
      "author": {
        "name": "dotCMS",
        "email": "support@dotcms.com",
        "url": "https://www.dotcms.com"
      },
      "homepage": "https://github.com/dotCMS/agent-toolkit",
      "repository": "https://github.com/dotCMS/agent-toolkit",
      "license": "MIT",
      "category": "development",
      "keywords": [
        "dotcms",
        "cms",
        "content-management",
        "vtl",
        "nextjs",
        "headless"
      ],
      "tags": [
        "dotcms",
        "cms",
        "content-management",
        "vtl",
        "nextjs",
        "headless"
      ],
      "skills": [
        "./skills/dotcms-create-sites",
        "./skills/dotcms-best-practices"
      ]
    }
  ]
}