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
Install
npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/craftcms-ops
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
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 --livere-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
- 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. - Escape by context. Never
|rawuser-influenced values;|e('js')inside JS strings;{{ csrfInput() }}in every POST form -csrfInput({ async: true })on cached pages. - Schema only through Project Config. Change it in the CP locally, commit
config/project/, runphp craft upon deploy. Production runsallowAdminChanges => false; never hand-edit the YAML. - Data changes are content migrations (
php craft migrate/create), tested on a copy of production - not CP clicking on live. - Production runs a queue worker. Blitz regeneration, Formie emails and integrations, transform pre-generation, and resaves are all queue jobs.
- Fix queries, then cache. Blitz for public pages; on Blitz-cached pages drop
{% cache %}(or setenableTemplateCachingfalse). - Logic lives in module services, not Twig - services are testable.
- 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 sloworderBy) ·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-sitelang; see itsreferences/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; itsreferences/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.
Reviews (0)
No reviews yet.
No comments yet.