# craft-content-modeling

Adopt this skill: https://proskills.md/skills/other/michtio-craftcms-claude-skills-skills-craft-content-modeling

Page: https://proskills.md/skills/other/michtio-craftcms-claude-skills-skills-craft-content-modeling
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/craft-content-modeling/SKILL.md
size: 8046
upstream: https://github.com/michtio/craftcms-claude-skills/blob/main/skills/craft-content-modeling/SKILL.md

````text
---
name: craft-content-modeling
description: "Craft CMS 5 content modeling — sections, entry types, fields, Matrix, relations, project config, and content architecture strategy. Covers choosing section types, designing entry types and field layouts, selecting field types, configuring Matrix and nested entries, relations and eager loading, and multi-site propagation."
when_to_use: "Triggers on: section types (single, channel, structure), entry types, field types, field layout design, field type selection, Matrix, nested entries, relatedTo, eager loading, .with()/.eagerly(), categories, tags, globals, global sets, preloadSingles, propagation, multi-site content, project config, YAML, content strategy, taxonomy, asset volumes, filesystems, image transforms, user groups, content permissions, entrify/entrification, CKEditor vs Matrix, CMS editions, multi-language, language groups, localization, translation method, field translation, content migration, field instances, Formie forms as elements vs project config, cross-environment Formie deployment, multi-site Formie translation, element index sources, elementSources, Entries index sidebar, tableAttributes, defaultSort, authoring schema from code (service layer vs project.yaml + pc/apply). Always use when planning content architecture, creating sections/fields, configuring Matrix, setting up relations, choosing field types, designing field layouts, planning multi-site propagation, or tidying the Entries element index. Do NOT trigger for PHP plugin/module development, custom field type code, front-end Twig, or buildchain."
---

# Craft CMS 5 — Content Modeling

How to structure content in Craft CMS 5. Sections, entry types, fields, Matrix,
relations, asset management, and strategic patterns for real projects.

This skill covers **content architecture** — what goes in the CP, how it's
organized, and how templates access it. For extending Craft with PHP
(plugins, modules, custom element types), see the `craftcms` skill.

## Companion Skills — Always Load Together

When this skill triggers, also load:

- **`craft-site`** — Template architecture, component patterns, routing. Required when content decisions affect how templates render data.
- **`craft-twig-guidelines`** — Twig coding standards. Required when writing any Twig examples or template code alongside content modeling.
- **`ddev`** — All commands run through DDEV. Required for running project config commands, Craft CLI, and content migrations.

## Documentation

- Entries: https://craftcms.com/docs/5.x/reference/element-types/entries.html
- Sections: https://craftcms.com/docs/5.x/reference/element-types/entries.html#sections
- Fields: https://craftcms.com/docs/5.x/system/fields.html
- Field types: https://craftcms.com/docs/5.x/reference/field-types/
- Matrix: https://craftcms.com/docs/5.x/reference/field-types/matrix.html
- Relations: https://craftcms.com/docs/5.x/system/relations.html
- Eager loading: https://craftcms.com/docs/5.x/development/eager-loading.html
- Project config: https://craftcms.com/docs/5.x/system/project-config.html

Use `WebFetch` on specific doc pages when a reference file doesn't cover enough detail.

## The Craft 5 Mental Model

**Everything is becoming an entry.** Entry types are global (shared across sections and
Matrix fields). Fields come from a global pool. This is the "entrification" of Craft — categories, tags, and globals are being unified into entries over a three-version arc:

- **Craft 4.4** — `entrify` CLI commands added to convert categories, tags, and globals to entries
- **Craft 5** — Categories, tags, and global sets are deprecated and discouraged for new projects. New category groups, tag groups, and global sets can still be created in the CP (the "New" buttons remain, gated by `allowAdminChanges`), and existing ones continue to work. A unified "Content" section replaces the fragmented entries view. Custom entry index pages (5.9.0) solve the sidebar organization concern.
- **Craft 6** — Categories, tags, and global sets will be removed entirely

For **new projects**, always use entries: Structure sections for hierarchical taxonomy, Channel sections for flat taxonomy, Singles for site-wide settings. For **existing projects**, migrate at your own pace using the `entrify` commands.

Three decisions define your content architecture:

1. **Which section type** organizes the content (Single, Channel, Structure)
2. **Which entry types** define its shape (global, reusable across contexts)
3. **Which relation strategy** connects content together (Entries fields, Matrix, CKEditor nested entries, or a combination)

## CMS Editions

Craft CMS has four editions (Solo, Team, Pro, Enterprise) that affect content modeling. The key distinction: if any section needs multiple custom user groups with per-group edit/view restrictions, you need **Pro or Enterprise** (multiple custom user groups are Pro+ only). Team includes one fixed "Team" group whose permissions are customizable for non-admins, plus a 5-user cap. See `references/users-and-permissions.md` for the full editions table and permissions architecture.

Choose the edition before modeling — it determines whether you can scope content access by user group, which affects section and field architecture.

## Section Type Decision

| Need | Section Type | URI Example |
|------|-------------|-------------|
| One-off page (homepage, about, contact) | **Single** | `__home__`, `about` |
| Site-wide settings (footer, header config) | **Single** (no URI, `preloadSingles`) | — |
| Flat collection (blog, news, events) | **Channel** | `blog/{slug}` |
| Hierarchical pages (docs, services) | **Structure** | `{parent.uri}/{slug}` |
| Taxonomy (topics, categories) | **Structure** (replaces categories) | `topics/{slug}` |
| Flat tags | **Channel** (replaces tags) | — |

### Section Properties

Beyond the type, sections have settings that matter for content architecture:

- **`maxAuthors`** (default 1) — allows multiple authors per entry (new in 5.0.0). Set higher for collaborative content.
- **`minAuthors`** (default 1, new in 5.10) — minimum number of authors required to save an entry. Set `1` to enforce that every entry has at least one author. Validated on save; setting `minAuthors > maxAuthors` is rejected by Craft's section validator. Combine with `maxAuthors` to define an exact range (`min: 1, max: 3` = "1 to 3 authors required").
- **`enableVersioning`** (default true) — version history for entries
- **`defaultPlacement`** — `'beginning'` or `'end'` for new entries in structures
- **`previewTargets`** — array of `{label, urlFormat}` objects defining where entries can be previewed. Default: primary entry page. Add custom targets for headless frontends, staging URLs, or PDF previews.

### Singles replace globals

Set `preloadSingles => true` in `config/general.php` to access singles as global
Twig variables by handle — identical to the old globals behavior but with drafts,
revisions, live preview, and scheduling.

```twig
{# With preloadSingles enabled #}
{{ siteSettings.footerText }}
{{ siteSettings.socialLinks.all() }}
```

**Caveat:** Singles always propagate to all sites. This is hard-coded.

### Structure queries for navigation

```twig
{% set topLevel = craft.entries.section('pages').level(1).all() %}
{% set children = craft.entries.descendantOf(entry).descendantDist(1).all() %}
{% set breadcrumbs = craft.entries.ancestorOf(entry).all() %}
{% set siblings = craft.entries.siblingOf(entry).all() %}
```

## Entry Types in Craft 5

Entry types are defined globally (Settings → Entry Types), then attached to
sections and Matrix fields. One entry type can serve multiple contexts.

Key implications:
- Changing an entry type's field layout affects **every** section and Matrix field using it
- Fields come from the global pool — same field definition reused everywhere
- Per-context name/handle/description overrides available (5.6.0+) — useful when the same entry type serves different purpose
````

## File: README.md
upstream: https://github.com/michtio/craftcms-claude-skills/blob/main/README.md

````text
# Craft CMS Claude Skills

> Production-ready [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skills, agents, and project templates for Craft CMS 5 development.

Built and maintained by [michtio](https://github.com/michtio). Covers both **plugin/module development** (extending Craft) and **site development** (content modeling, Twig templates, front-end architecture).

## Support

If this project saves you time, consider supporting its development:

- [GitHub Sponsors](https://github.com/sponsors/michtio)
- [Buy Me a Coffee](https://buymeacoffee.com/michtio)

## Quick Start

### 1. Install

```bash
# Claude Code Plugin (recommended)
# First time: add the marketplace, then install
/plugin marketplace add michtio/craftcms-claude-skills
/plugin install craftcms-claude-skills@craftcms-claude-skills

# Or via Vercel Skills CLI
npx skills add michtio/craftcms-claude-skills --all

# Or clone manually
git clone https://github.com/michtio/craftcms-claude-skills.git ~/.claude/craftcms-claude-skills
cd ~/.claude/craftcms-claude-skills && bash install.sh
```

### 2. Set Up Your Project

Open Claude Code in your Craft project and say:

```
Set up Claude for this Craft project
```

The `craft-project-setup` skill detects your project type (plugin, site, module, hybrid, or monorepo) and generates a tailored `CLAUDE.md` and `.claude/rules/` directory.

### 3. Start Building

The skills trigger automatically based on what you're doing. Just describe what you need:

```
Build a blog with topics, authors, and a flexible body builder using CKEditor
```

Claude loads the right skills, follows Craft conventions, and uses the correct field handles, DDEV commands, and project config workflow.

## Example Prompts

Just describe what you need — skills trigger automatically and produce high-quality results. A few to show the range, grouped by domain:

**Content modeling & architecture**

```
Plan the content architecture for a multi-language corporate site with
news, team members, office locations, and a service catalog. We need
English, German, and French with subfolder-per-language routing.
```

**Plugins & modules**

```
Build a custom element type for "Job Listings" with postDate/expiryDate
status, a categories relation for departments, and a CP edit page with
field layout designer.
```

**Control panel & author experience**

```
I need a modal dialog for my Craft plugin that opens when clicking
"Add Item", shows a form with name and handle fields, POSTs to my
plugin's save action, and closes on success. Make it keyboard accessible.
```

**Front-end & Twig**

```
Create an atomic button component that supports links, form submits,
and disabled states. It needs size variants and a loading spinner option.
```

```
Build a member area with registration, login, password reset, and
profile editing. Users should be in the "Members" group and only see
content in the gated section.
```

**Hosting & deployment**

```
Set this project up to deploy on Servd: Servd asset storage, static
caching with Blitz in reverse-proxy mode, and the dedicated queue
runner. Document the constraints in CLAUDE.md.
```

```
This project deploys to fortrabbit. Add a deploy file that keeps our
asset volumes, move the queue into a worker job, and pull the
production database into DDEV.
```

```
Configure Redis for cache, sessions, and mutex in our Craft project.
We're running DDEV locally and deploying to a VPS with Redis installed.
```

See [docs/prompt-guide.md](docs/prompt-guide.md) for 40+ prompts organized by task type — content modeling, plugin development, field types, security, Twig, CP/JS, configuration & deployment, testing, and headless.

## What's Inside

### Skills

| Skill | Track | Key Coverage |
|-------|-------|--------------|
| `craftcms` | Plugin | Elements, queries, services, controllers, migrations, events, GraphQL, configuration, caching, permissions, CP templates (form macros, settings, navigation), CP components (widgets, utilities, slideouts), CP UI patterns (tri-state, condition builders, asset bundles), console commands (80+ commands), debugging, identity protocols for SSO/SCIM plugins. 31 reference files. |
| `craft-php-guidelines` | Plugin | PHPDocs, section headers, naming, class organization, ECS/PHPStan. 6 reference files. |
| `craft-content-modeling` | Site | Sections, entry types, fields, Matrix, relations, eager loading, entrification. Reuse-first field workflow. 7 reference files. |
| `craft-site` | Site | Atomic design, component patterns, routing, Vite, auth flows, search, feeds, headless, template caching. 20 reference files. |
| `craft-plugins` | Plugin References | Name-routed index of third-party plugin guidance (config, Twig/PHP API, migrations, deployment, pitfalls), discoverable from any task altitude. 24 plugin references. |
| `craft-twig-guidelines` | Site | Variable naming, null handling, whitespace, include isolation, Craft helpers, `collect()`. |
| `craft-garnish` | Plugin | Garnish CP JavaScript: class system, UI widgets, drag system, ARIA/focus, Craft.* pattern. 5 reference files. |
| `craft-pest` | Plugin | Testing with Pest and `markhuot/craft-pest-core`: database isolation (rollback is opt-in, env overrides are cwd-bound), factories, HTTP/queue/DB assertions, Craft internals that bite in tests, shared-install hygiene, CI test jobs. 5 reference files. |
| `craft-plugin-release` | Plugin | Release mechanics: composer.json version key, Packagist verification via `repo.packagist.org/p2`, tag recreation risk model, GitHub release objects vs tags, `gh release` pitfalls, branch promotion hygiene, shared-library release ordering, Composer path repositories, `git filter-repo` purges. 2 reference files. |
| `ddev` | Shared | Commands, services, configuration, Xdebug, site sharing, troubleshooting. |
| `craft-project-setup` | Shared | Project scaffolding, upgrade, and audit. Generates CLAUDE.md, .claude/rules/, .claude/settings.local.json (permissions). Gap analysis for existing configs. |
| `craft-cloud` | Shared | Craft Cloud serverless hosting: `craft-cloud.yaml`, Build → Migrate → Release pipeline, the `craftcms/cloud` extension, edge image transforms, static caching + ESI, MySQL 8 / Postgres 15 constraints, Console command runner, plugin Cloud-compatibility, headless apps + request signing, self-hosted → Cloud migration. 13 reference files. |
| `craft-fortrabbit` | Shared | fortrabbit managed PHP hosting: git push via the GitHub App, the Craft software template (build + post-deploy commands, merge strategy, `/config/project` replace pattern), the `.fortrabbit/deploy.yml` deploy file, `CRAFT_*` ENV vars mapped from `FORTRABBIT_DB_*`, persistent storage + rsync, MySQL over SSH, queue and transforms in a worker job, crons, platform limits. 5 reference files. |
| `servd` | Shared | Servd managed hosting: git push-to-deploy + `servd.yaml`, local → staging → production sync, the `servd/craft-asset-storage` plugin (svdcdn CDN, off-server transforms), Servd static caching + Blitz reverse-proxy mode, MariaDB/MySQL over SSH, backups, Dedicated Queue Runner, ephemeral filesystem. 6 reference files. |

14 skills, 124 reference files. Skills load automatically and declare companion skills so related knowledge loads together. See [docs/skills-overview.md](docs/skills-overview.md) for the full breakdown.

### Agents

| Agent | Model | Purpose |
|-------|-------|---------|
| `craft-planner` | Opus | Decompose features into vertical slices with verification gates. Can research/audit public plugins via `gh` and `git clone`. |
| `craft-feature-builder` | Opus | Build plugin code feature by feature with automated + manual test gates |
| `craft-site-builder` | Opus | Site templates and components feature by feature with build-verify gates |
| `craft-debugger` | Sonnet | Systematic bug investigation |
| `craft-code-reviewer` | Sonnet | Full-stack review against a structured checklist: PHP, Twig, JS, CSS, config |
| `craft-code-reviewer-deep` | Opus | Deep review f
````
