Claude Skill

craftcms-ops

Craft CMS 5 development - content modeling, Twig templating, element queries, GraphQL, plugins, and the Craft 4-to-5 Matrix-as-entries change. Use for: craft cms, craftcms, craft 5, twig, pixel & tonic, matrix field, entry types, sections, element query, eager loading, blitz, pro

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download 0xDarkMatter-claude-mods-skills_craftcms-ops-fa93328.zip · 58 KB

Install

skills CLI npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/craftcms-ops
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
Git git clone https://github.com/0xDarkMatter/claude-mods.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Craft CMS Operations

Versions verified 2026-10-05 against Packagist and the official docs. Craft 5.x is current (5.11); Craft 4 and 3 are past security support; Craft 6 is in alpha. scripts/check-craft-facts.py --live re-checks the plugin majors on a schedule.

The recurring agency shape: Craft 5 (or a 4/3 site awaiting upgrade) on DDEV, with SEOmatic, Blitz, Formie, and CKEditor, a Vite (or legacy Laravel Mix) front end, and modules tested with Codeception and ECS. This file is the procedure and the router; each topic lives in one reference.

Step 1 - Orient before touching anything

Check Where Tells you
Craft + plugin versions composer.json, ddev composer show craftcms/cms Which line of the version matrix applies - Craft 4 and 5 APIs differ
Local environment .ddev/config.yaml PHP/DB versions; run everything as ddev craft, ddev composer, ddev npm
Schema config/project/*.yaml Source of truth for sections, fields, entry types, plugin settings
Config config/general.php, config/<plugin>.php, .env Environment-specific behaviour (devMode, allowAdminChanges, caching)
Front-end build package.json + config/vite.php, or webpack.mix.js craft-vite or Laravel Mix
Templates templates/_layouts, _partials, _partials/entry/<type>.twig Layout inheritance and element partials
PHP modules/, tests/, codeception.yml, ecs.php Where logic and tests live
Page cache config/blitz.php, Blitz utility Whether what you see is cached HTML - check before debugging "my change isn't showing"

Step 2 - Route the task

Task Read
Listing pages, relations, Matrix/nested entries, pagination, multi-site element-queries.md
Printing anything user-influenced, forms that POST, JS data, rich text output twig-security.md
Meta tags, JSON-LD, sitemaps, robots.txt, hreflang seomatic.md
Static caching, "changes don't show", cache warming, dynamic bits on cached pages blitz.md
Building, theming, or debugging forms; spam; form emails not sending formie.md
Rich-text fields, nested entries inside rich text, Redactor conversion ckeditor.md
Craft on DDEV: the craftcms type, ddev craft, Craft's upload_dirs (generic DDEV: ddev-ops) ddev.md
Tests for modules/plugins, fixtures, ECS/PHPStan codeception.md
Front-end assets, Vite dev server, critical CSS craft-vite.md
Moving off Laravel Mix/Webpack, or Vue 2 to Vue 3 frontend-upgrade-ops (the full migration playbook)
Upgrading Craft 3 → 4 → 5, plugin version lines, Craft 6 status upgrades.md
Slow pages, images, queue setup, production config performance.md
Core Web Vitals failing (LCP, INP, CLS), PageSpeed or Search Console flags web-perf-ops (field data first; its references/craft.md maps the Craft levers)
Headless front ends, GraphQL schemas and tokens graphql.md
Modules, plugins, events, migrations, queue jobs plugin-development.md
Modeling a new flexible page type assets/entry-type-field-layout.md

Step 3 - Hold the non-negotiables

  1. Eager-load before you loop. .with([...]) up front; .eagerly() inside shared partials (Craft 5 only). One query per card is the most common Craft perf bug.
  2. Escape by context. Never |raw user-influenced values; |e('js') inside JS strings; {{ csrfInput() }} in every POST form - csrfInput({ async: true }) on cached pages.
  3. Schema only through Project Config. Change it in the CP locally, commit config/project/, run php craft up on deploy. Production runs allowAdminChanges => false; never hand-edit the YAML.
  4. Data changes are content migrations (php craft migrate/create), tested on a copy of production - not CP clicking on live.
  5. Production runs a queue worker. Blitz regeneration, Formie emails and integrations, transform pre-generation, and resaves are all queue jobs.
  6. Fix queries, then cache. Blitz for public pages; on Blitz-cached pages drop {% cache %} (or set enableTemplateCaching false).
  7. Logic lives in module services, not Twig - services are testable.
  8. Stay on the latest Craft 5 patch. Craft ships regular Twig/RCE security fixes.

Version matrix

Package Craft 3 Craft 4 Craft 5 (current)
craftcms/cms 3.9 (EOL) 4.18 (EOL Apr 2026) Craft 5.x (5.11); Craft 6 in alpha
nystudio107/craft-seomatic 3.x 4.x SEOmatic 5
putyourlightson/craft-blitz 3.x 4.x Blitz 5 (5.13 needs Craft 5.6+)
verbb/formie 1.x 2.x Formie 3 (Formie 4 in beta)
Rich text Redactor Redactor or craftcms/ckeditor 3.x CKEditor plugin 5.x (needs Craft 5.10+; 4.x below that)
nystudio107/craft-vite 1.x 4.x craft-vite 5
nystudio107/craft-imageoptimize 1.x 4.x ImageOptimize 5
spacecatninja/imager-x 3.x 4.x Imager-X 6 (5.x still maintained)
codeception/codeception match core's require-dev match core's require-dev Codeception 5

Requirements for Craft 5: PHP 8.2+, MySQL 8.0.17+ / MariaDB 10.4.6+ / PostgreSQL 13+. Details and plugin upgrade notes: upgrades.md.

Everyday commands

Command (prefix ddev locally) Does
craft up Pending migrations + Project Config - run on every deploy
craft project-config/apply / project-config/rebuild Apply YAML to the DB / rebuild YAML from the DB
craft clear-caches/all Data, template, and asset caches
craft queue/run / queue/info / queue/retry all Work and inspect the queue
craft blitz/cache/refresh Refresh Blitz after template deploys (Blitz tracks content, not templates)
craft migrate/create <name> New content migration
craft make <type> Scaffold modules/plugins/components (craftcms/generator)
craft entrify/categories <group> Convert categories (or tags, global-set) to entries

Craft 5 content model

Concept What it is Craft 5 change
Section Single, Channel, or Structure; holds entry types + URI formats -
Entry type The unit of content shape Global and reusable across sections and Matrix fields
Field Reusable input Global, with multi-instance use in one layout
Matrix field Repeatable nested content Stores nested entries, not blocks
CKEditor field Rich text Can hold nested entries inline
Element partials _partials/entry/<typeHandle>.twig .render() renders nested entries through them
Project Config config/project/ YAML Source of truth - commit it

Pick the section type by shape: Single for one-off pages (home, contact), Channel for streams (news, events), Structure for hierarchies (pages, docs). Prefer flat entry types plus a Matrix "page builder" field over many near-identical sections. Starter shape: entry-type-field-layout.md.

Gotchas

Symptom Cause Fix
Listing page runs hundreds of queries Relation fetched per item .with() / .eagerly()
Change visible in CP, not on site Blitz/CDN serving cached HTML blitz.md
Form submissions save, emails never send Queue not running in production Queue daemon (performance.md)
Assets unstyled in production only Vite 5+ manifest is in dist/.vite/ Set manifestPath (craft-vite.md)
{% set seomatic.meta.seoTitle = ... %} does nothing set only reads {% do seomatic.meta.seoTitle('...') %}
Staging copy of the site got indexed / prod de-indexed SEOmatic environment wrong Check robots in view-source (seomatic.md)
Project Config conflicts between developers CP edits on shared/prod environments allowAdminChanges false outside local; one schema change per PR
Event handler fires several times per save Drafts, revisions, propagation Guard with ElementHelper::isDraftOrRevision() + propagating
craft.matrixBlocks() errors after upgrade Removed in Craft 5 craft.entries().field(...).owner(...)

Bundled resources

File Use
assets/entry-type-field-layout.md Content-modeling starter: section + entry type + Matrix-as-entries, mapped to Project Config
assets/craft-facts.json The version facts this skill documents (package, major, prose token)
scripts/check-craft-facts.py Staleness verifier: --offline (prose still states the facts) / --live (Packagist majors)

See also

  • ddev-ops (generic DDEV: version pinning, env files, snapshots and sanitised pulls, Mutagen, add-ons, Xdebug, and an auditor for .ddev/ mistakes)
  • laravel-ops (Composer/PHP tooling; Craft 6 is Laravel-based) · sql-ops (indexes behind slow orderBy) · nginx-ops (serving Craft, Blitz rewrites) · perf-ops (profiling) · tailwind-ops · playwright-ops (browser tests against the DDEV URL)
  • web-perf-ops (Core Web Vitals: CrUX/RUM first, then the failing subpart; Blitz, transforms, craft-vite critical CSS and SEOmatic/Formie script placement as INP/LCP levers)
  • frontend-upgrade-ops (Laravel Mix or Webpack to Vite via craft-vite, Vue 2 to Vue 3, Vue islands in Twig, and when a widget should become Alpine instead)
  • a11y-ops (WCAG 2.2 for Twig sites: heading levels across partials, asset alt text, Formie and CKEditor markup, multi-site lang; see its references/server-rendered-templates.md)
  • security-ops (Craft/Twig/PHP security: CSRF and Formie, allowAnonymous, devMode and the security key, GraphQL scoping, uploads, advisories and Craft 3/4 end of life; its references/craft-*.md, twig-*.md, php-*.md)
  • Craft 5 docs · Plugin Store · Craft security advisories

Why this shape: a 2026 survey of 57 Craft-agency repositories found Craft in 36 (Craft 5 ×17, 4 ×13, 3 ×6), DDEV in 36, SEOmatic in 33, Blitz 21, Formie 18, CKEditor 18, Laravel Mix 18 versus craft-vite 12, Tailwind 12, ECS 11, and Codeception 10. The references follow that frequency; upgrades matter because half the Craft sites were on an EOL major.

Files (claude-mods)
  • assets
    • craft-facts.json 1.6 KB
      Loading…
    • entry-type-field-layout.md 3.3 KB
      Loading…
  • references
    • blitz.md 8.2 KB
      Loading…
    • ckeditor.md 5.2 KB
      Loading…
    • codeception.md 7.5 KB
      Loading…
    • craft-vite.md 7.3 KB
      Loading…
    • ddev.md 6.4 KB
      Loading…
    • element-queries.md 6.6 KB
      Loading…
    • formie.md 7.2 KB
      Loading…
    • graphql.md 4.1 KB
      Loading…
    • performance.md 10 KB
      Loading…
    • plugin-development.md 5.2 KB
      Loading…
    • seomatic.md 7.5 KB
      Loading…
    • twig-security.md 8.4 KB
      Loading…
    • upgrades.md 7.6 KB
      Loading…
  • scripts
    • check-craft-facts.py 10.8 KB
      Loading…
  • tests
    • run.sh 9.6 KB
      Loading…
  • SKILL.md 11.5 KB
    ---
    name: craftcms-ops
    description: "Craft CMS 3/4/5 agency site builds: Matrix-as-entries content modeling, Twig and element queries, eager loading, output escaping and CSRF, and the usual plugin stack - SEOmatic, Blitz, Formie, CKEditor, craft-vite - plus DDEV, Codeception, image transforms, the queue, and 3-to-4-to-5 upgrades. Use when building, debugging, securing, speeding up, or upgrading a Craft site, or editing its Twig templates, config/project, or any of those plugins."
    license: MIT
    allowed-tools: "Read Write Bash"
    metadata:
      author: claude-mods
      related-skills: "ddev-ops, laravel-ops, sql-ops, nginx-ops, perf-ops, web-perf-ops, frontend-upgrade-ops, tailwind-ops, playwright-ops, a11y-ops, security-ops"
    ---
    
    # Craft CMS Operations
    
    > Versions verified 2026-10-05 against Packagist and the official docs. Craft 5.x is
    > current (5.11); Craft 4 and 3 are past security support; Craft 6 is in alpha.
    > `scripts/check-craft-facts.py --live` re-checks the plugin majors on a schedule.
    
    The recurring agency shape: Craft 5 (or a 4/3 site awaiting upgrade) on DDEV, with
    SEOmatic, Blitz, Formie, and CKEditor, a Vite (or legacy Laravel Mix) front end, and
    modules tested with Codeception and ECS. This file is the procedure and the router;
    each topic lives in one reference.
    
    ## Step 1 - Orient before touching anything
    
    | Check | Where | Tells you |
    |-------|-------|-----------|
    | Craft + plugin versions | `composer.json`, `ddev composer show craftcms/cms` | Which line of the [version matrix](#version-matrix) applies - Craft 4 and 5 APIs differ |
    | Local environment | `.ddev/config.yaml` | PHP/DB versions; run everything as `ddev craft`, `ddev composer`, `ddev npm` |
    | Schema | `config/project/*.yaml` | Source of truth for sections, fields, entry types, plugin settings |
    | Config | `config/general.php`, `config/<plugin>.php`, `.env` | Environment-specific behaviour (`devMode`, `allowAdminChanges`, caching) |
    | Front-end build | `package.json` + `config/vite.php`, or `webpack.mix.js` | craft-vite or Laravel Mix |
    | Templates | `templates/_layouts`, `_partials`, `_partials/entry/<type>.twig` | Layout inheritance and element partials |
    | PHP | `modules/`, `tests/`, `codeception.yml`, `ecs.php` | Where logic and tests live |
    | Page cache | `config/blitz.php`, Blitz utility | Whether what you see is cached HTML - check before debugging "my change isn't showing" |
    
    ## Step 2 - Route the task
    
    | Task | Read |
    |------|------|
    | Listing pages, relations, Matrix/nested entries, pagination, multi-site | [element-queries.md](references/element-queries.md) |
    | Printing anything user-influenced, forms that POST, JS data, rich text output | [twig-security.md](references/twig-security.md) |
    | Meta tags, JSON-LD, sitemaps, robots.txt, hreflang | [seomatic.md](references/seomatic.md) |
    | Static caching, "changes don't show", cache warming, dynamic bits on cached pages | [blitz.md](references/blitz.md) |
    | Building, theming, or debugging forms; spam; form emails not sending | [formie.md](references/formie.md) |
    | Rich-text fields, nested entries inside rich text, Redactor conversion | [ckeditor.md](references/ckeditor.md) |
    | Craft on DDEV: the `craftcms` type, `ddev craft`, Craft's `upload_dirs` (generic DDEV: `ddev-ops`) | [ddev.md](references/ddev.md) |
    | Tests for modules/plugins, fixtures, ECS/PHPStan | [codeception.md](references/codeception.md) |
    | Front-end assets, Vite dev server, critical CSS | [craft-vite.md](references/craft-vite.md) |
    | Moving off Laravel Mix/Webpack, or Vue 2 to Vue 3 | `frontend-upgrade-ops` (the full migration playbook) |
    | Upgrading Craft 3 → 4 → 5, plugin version lines, Craft 6 status | [upgrades.md](references/upgrades.md) |
    | Slow pages, images, queue setup, production config | [performance.md](references/performance.md) |
    | Core Web Vitals failing (LCP, INP, CLS), PageSpeed or Search Console flags | `web-perf-ops` (field data first; its `references/craft.md` maps the Craft levers) |
    | Headless front ends, GraphQL schemas and tokens | [graphql.md](references/graphql.md) |
    | Modules, plugins, events, migrations, queue jobs | [plugin-development.md](references/plugin-development.md) |
    | Modeling a new flexible page type | [assets/entry-type-field-layout.md](assets/entry-type-field-layout.md) |
    
    ## Step 3 - Hold the non-negotiables
    
    1. **Eager-load before you loop.** `.with([...])` up front; `.eagerly()` inside shared
       partials (Craft 5 only). One query per card is the most common Craft perf bug.
    2. **Escape by context.** Never `|raw` user-influenced values; `|e('js')` inside JS
       strings; `{{ csrfInput() }}` in every POST form - `csrfInput({ async: true })` on
       cached pages.
    3. **Schema only through Project Config.** Change it in the CP locally, commit
       `config/project/`, run `php craft up` on deploy. Production runs
       `allowAdminChanges => false`; never hand-edit the YAML.
    4. **Data changes are content migrations** (`php craft migrate/create`), tested on a
       copy of production - not CP clicking on live.
    5. **Production runs a queue worker.** Blitz regeneration, Formie emails and
       integrations, transform pre-generation, and resaves are all queue jobs.
    6. **Fix queries, then cache.** Blitz for public pages; on Blitz-cached pages drop
       `{% cache %}` (or set `enableTemplateCaching` false).
    7. **Logic lives in module services**, not Twig - services are testable.
    8. **Stay on the latest Craft 5 patch.** Craft ships regular Twig/RCE security fixes.
    
    ## Version matrix
    
    | Package | Craft 3 | Craft 4 | Craft 5 (current) |
    |---------|---------|---------|-------------------|
    | `craftcms/cms` | 3.9 (EOL) | 4.18 (EOL Apr 2026) | Craft 5.x (5.11); Craft 6 in alpha |
    | `nystudio107/craft-seomatic` | 3.x | 4.x | SEOmatic 5 |
    | `putyourlightson/craft-blitz` | 3.x | 4.x | Blitz 5 (5.13 needs Craft 5.6+) |
    | `verbb/formie` | 1.x | 2.x | Formie 3 (Formie 4 in beta) |
    | Rich text | Redactor | Redactor or `craftcms/ckeditor` 3.x | CKEditor plugin 5.x (needs Craft 5.10+; 4.x below that) |
    | `nystudio107/craft-vite` | 1.x | 4.x | craft-vite 5 |
    | `nystudio107/craft-imageoptimize` | 1.x | 4.x | ImageOptimize 5 |
    | `spacecatninja/imager-x` | 3.x | 4.x | Imager-X 6 (5.x still maintained) |
    | `codeception/codeception` | match core's `require-dev` | match core's `require-dev` | Codeception 5 |
    
    Requirements for Craft 5: PHP 8.2+, MySQL 8.0.17+ / MariaDB 10.4.6+ / PostgreSQL 13+.
    Details and plugin upgrade notes: [upgrades.md](references/upgrades.md).
    
    ## Everyday commands
    
    | Command (prefix `ddev` locally) | Does |
    |---------------------------------|------|
    | `craft up` | Pending migrations + Project Config - run on every deploy |
    | `craft project-config/apply` / `project-config/rebuild` | Apply YAML to the DB / rebuild YAML from the DB |
    | `craft clear-caches/all` | Data, template, and asset caches |
    | `craft queue/run` / `queue/info` / `queue/retry all` | Work and inspect the queue |
    | `craft blitz/cache/refresh` | Refresh Blitz after template deploys (Blitz tracks content, not templates) |
    | `craft migrate/create <name>` | New content migration |
    | `craft make <type>` | Scaffold modules/plugins/components (`craftcms/generator`) |
    | `craft entrify/categories <group>` | Convert categories (or `tags`, `global-set`) to entries |
    
    ## Craft 5 content model
    
    | Concept | What it is | Craft 5 change |
    |---------|-----------|----------------|
    | **Section** | Single, Channel, or Structure; holds entry types + URI formats | - |
    | **Entry type** | The unit of content shape | **Global and reusable** across sections and Matrix fields |
    | **Field** | Reusable input | **Global**, with multi-instance use in one layout |
    | **Matrix field** | Repeatable nested content | Stores **nested entries**, not blocks |
    | **CKEditor field** | Rich text | Can hold **nested entries** inline |
    | **Element partials** | `_partials/entry/<typeHandle>.twig` | `.render()` renders nested entries through them |
    | **Project Config** | `config/project/` YAML | Source of truth - commit it |
    
    Pick the section type by shape: **Single** for one-off pages (home, contact),
    **Channel** for streams (news, events), **Structure** for hierarchies (pages, docs).
    Prefer flat entry types plus a Matrix "page builder" field over many near-identical
    sections. Starter shape: [entry-type-field-layout.md](assets/entry-type-field-layout.md).
    
    ## Gotchas
    
    | Symptom | Cause | Fix |
    |---------|-------|-----|
    | Listing page runs hundreds of queries | Relation fetched per item | `.with()` / `.eagerly()` |
    | Change visible in CP, not on site | Blitz/CDN serving cached HTML | [blitz.md](references/blitz.md#debugging-my-change-isnt-showing) |
    | Form submissions save, emails never send | Queue not running in production | Queue daemon ([performance.md](references/performance.md#queue)) |
    | Assets unstyled in production only | Vite 5+ manifest is in `dist/.vite/` | Set `manifestPath` ([craft-vite.md](references/craft-vite.md)) |
    | `{% set seomatic.meta.seoTitle = ... %}` does nothing | `set` only reads | `{% do seomatic.meta.seoTitle('...') %}` |
    | Staging copy of the site got indexed / prod de-indexed | SEOmatic environment wrong | Check robots in view-source ([seomatic.md](references/seomatic.md#environments)) |
    | Project Config conflicts between developers | CP edits on shared/prod environments | `allowAdminChanges` false outside local; one schema change per PR |
    | Event handler fires several times per save | Drafts, revisions, propagation | Guard with `ElementHelper::isDraftOrRevision()` + `propagating` |
    | `craft.matrixBlocks()` errors after upgrade | Removed in Craft 5 | `craft.entries().field(...).owner(...)` |
    
    ## Bundled resources
    
    | File | Use |
    |------|-----|
    | `assets/entry-type-field-layout.md` | Content-modeling starter: section + entry type + Matrix-as-entries, mapped to Project Config |
    | `assets/craft-facts.json` | The version facts this skill documents (package, major, prose token) |
    | `scripts/check-craft-facts.py` | Staleness verifier: `--offline` (prose still states the facts) / `--live` (Packagist majors) |
    
    ## See also
    
    - `ddev-ops` (generic DDEV: version pinning, env files, snapshots and sanitised pulls,
      Mutagen, add-ons, Xdebug, and an auditor for `.ddev/` mistakes)
    - `laravel-ops` (Composer/PHP tooling; Craft 6 is Laravel-based) · `sql-ops` (indexes behind
      slow `orderBy`) · `nginx-ops` (serving Craft, Blitz rewrites) · `perf-ops` (profiling) ·
      `tailwind-ops` · `playwright-ops` (browser tests against the DDEV URL)
    - `web-perf-ops` (Core Web Vitals: CrUX/RUM first, then the failing subpart; Blitz, transforms,
      craft-vite critical CSS and SEOmatic/Formie script placement as INP/LCP levers)
    - `frontend-upgrade-ops` (Laravel Mix or Webpack to Vite via craft-vite, Vue 2 to Vue 3,
      Vue islands in Twig, and when a widget should become Alpine instead)
    - `a11y-ops` (WCAG 2.2 for Twig sites: heading levels across partials, asset alt text, Formie
      and CKEditor markup, multi-site `lang`; see its `references/server-rendered-templates.md`)
    - `security-ops` (Craft/Twig/PHP security: CSRF and Formie, `allowAnonymous`, devMode and the
      security key, GraphQL scoping, uploads, advisories and Craft 3/4 end of life; its
      `references/craft-*.md`, `twig-*.md`, `php-*.md`)
    - [Craft 5 docs](https://craftcms.com/docs/5.x/) · [Plugin Store](https://plugins.craftcms.com/) ·
      [Craft security advisories](https://github.com/craftcms/cms/security/advisories)
    
    **Why this shape:** a 2026 survey of 57 Craft-agency repositories found Craft in 36
    (Craft 5 ×17, 4 ×13, 3 ×6), DDEV in 36, SEOmatic in 33, Blitz 21, Formie 18,
    CKEditor 18, Laravel Mix 18 versus craft-vite 12, Tailwind 12, ECS 11, and Codeception
    10. The references follow that frequency; upgrades matter because half the Craft sites
    were on an EOL major.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.