README

Production-ready Claude Code skills, agents, and project templates for Craft CMS 5 development.

Built and maintained by 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:

Quick Start

1. Install

# Claude Code Plugin (recommended)
# First time: add the marketplace, then install
/plugin marketplace add michtio/craftcms-claude-skills
/plugin install craftcms-claude-skills@michtio/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.

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 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. 30 reference files.
`craft-php-guidelines`	Plugin	PHPDocs, section headers, naming, class organization, ECS/PHPStan. 5 reference files.
`craft-content-modeling`	Site	Sections, entry types, fields, Matrix, relations, eager loading, entrification. Reuse-first field workflow. 6 reference files.
`craft-site`	Site	Atomic design, component patterns, routing, Vite, auth flows, search, feeds, headless. 18 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. 23 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.
`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, self-hosted → Cloud migration. 12 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.

11 skills, 105 reference files. Skills load automatically and declare companion skills so related knowledge loads together. See 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 for high-stakes PRs (release branches, security, migrations, multi-service flows): cross-file data flow, untested paths, race conditions, scale concerns

Agents build feature by feature (vertical slices), not layer by layer. Tests are written alongside each layer, not batched at the end. Manual testing gates (required + optional) are identified per feature. The builder's prevention rules map directly to the reviewer's checklist across PHP, Twig, JS, and CSS; craft-code-reviewer-deep (Opus) goes further for high-stakes changes. See docs/agents.md for details.

Plugin Reference Library

23 Craft plugins with detailed configuration, Twig/PHP API, and common pitfalls — indexed and name-routed by the craft-plugins skill, so they surface from front-end, PHP, migration, and deployment tasks alike:

View all 23 plugin references

Plugin	Author	Key Surface
SEOmatic	nystudio107	Meta cascade, JSON-LD, sitemaps, GraphQL
Blitz	putyourlightson	Static caching, Cloudflare, dynamic content, purgers
Formie	verbb	Form rendering, Tailwind theming, submissions, hooks
ImageOptimize	nystudio107	Responsive images, transforms, loading strategies
CKEditor	craftcms	Rich text, nested entries, HTML Purifier
Sprig	putyourlightson	Reactive Twig components (htmx)
Element API	craftcms	JSON API endpoints
Retour	nystudio107	Redirects, 404 tracking
Navigation	verbb	Menu node querying, active states
Hyper	verbb	Link fields, button integration
Colour Swatches	craftpulse	Color palettes, Tailwind class mapping
Password Policy	craftpulse	Validation rules, HIBP check
Typogrify	nystudio107	Typography filters, widow prevention
Cache Igniter	putyourlightson	CDN cache warming
Knock Knock	verbb	Staging password protection
Elements Panel	putyourlightson	Debug toolbar, N+1 detection
Sherlock	putyourlightson	Security scanning
Embedded Assets	spicyweb	oEmbed as assets
Amazon SES	putyourlightson	SES mail transport
Timeloop	craftpulse	Recurring dates
Feed Me	craftcms	Data import from XML/JSON/CSV, CLI automation
Imager-X	spacecatninja	Advanced image transforms, named presets, effects
Vite	nystudio107	Asset loading (`craft.vite.*`), critical CSS, dev server, manifest

Documentation

Guide	What it covers
Getting Started	Installation, project setup, how skills auto-trigger, first steps
Skills Overview	All 11 skills with triggers, companion skills, reference counts, boundaries
Prompt Guide	40+ real-world prompts organized by task type
Agents	6 agents with tools, gate patterns, composition examples
Contributing	Adding plugin references, improving skills, reporting issues

Requirements

Claude Code installed and configured
DDEV for local Craft CMS development
Craft CMS 5.x
Bash (macOS/Linux) for the install script

Versioning

This package follows its own semantic versioning, driven by the pack's own content — it is not pinned to Craft's minor releases:

Patch (e.g. 1.6.0 → 1.6.1) — accuracy fixes, corrections, small content updates
Minor (e.g. 1.5.x → 1.6.0) — new skills, new plugin references, significant content additions
Major (1.x → 2.x) — Craft's next major (5.x → 6.x, where APIs break) or a major reorganization of the pack

The pack targets Craft CMS 5, latest minor (currently 5.10). Behaviour specific to a Craft minor is annotated inline in the content (e.g. "since 5.10.0"), so a single line serves projects on any Craft 5 minor — the minors are additive and backward-compatible. New content like a hosting skill or plugin reference is a feature of the pack, independent of which Craft minor is current.

Development happens on main. The 1.4.x branch is a frozen snapshot targeting Craft 5.9 — it received a final quality release and no longer takes new work; all new development lands on main. The release-validation workflow enforces that manifest versions match the release tag.

Roadmap

Upgrade guide (Craft 3→4, 4→5, 3→5) with deprecated plugin mapping and migration paths
DDEV skill expansion (Xdebug deep-dive, custom services, production parity)
Commerce skill (products, variants, orders, carts, payments -- separate skill)
CKEditor 4→5 migration guide (config conversion, custom styles, plugin mapping, HTML cleanup)
More plugin references (Neo, Scout, Campaign)

Contributing

Contributions welcome. See docs/contributing.md for how to add plugin references, improve skills, and report issues.

For PHP consumers (composer)

The same repo also ships as a small composer package, exposing the bundled skills' markdown to PHP code through a thin static helper. The primary consumer is craftpulse/craft-cortex — a Craft CMS 5 MCP server plugin that surfaces these skills as MCP prompts and resources to AI agents.

composer require michtio/craftcms-claude-skills

use Michtio\CraftCmsClaudeSkills\Skills;

Skills::skillNames();
// ['craft-content-modeling', 'craft-garnish', 'craft-php-guidelines', ...]

Skills::content('craftcms');
// Full SKILL.md content as a string

Skills::references('craftcms');
// ['architecture', 'caching', 'conditions', ...]

Skills::referenceContent('craftcms', 'elements');
// Full reference markdown as a string

Skills::agentNames();
// ['craft-code-reviewer', 'craft-debugger', 'craft-feature-builder', ...]

Skills::agentContent('craft-debugger');
// Full agent markdown (frontmatter + body) as a string

The helper is read-only and does no caching — wrap it in your own registry if you need that. PHP 8.2+.

Acknowledgements

Thanks to the people whose contributions and work have improved this pack:

William Bocchinelli (@willbocc) — element-index sources guidance for content modeling (PR #7).
John Henry (@john-henry) — the Craft CP UI & Brand style guide that prompted the v1.9.0 control-panel UI reconciliation pass.

License

MIT -- see LICENSE.

michtio / craftcms-claude-skills

Maintainers

Package info

Fund package maintenance!

Statistics

Security