ghost-theme

name

ghost-theme

description

Build, customize, and deploy Ghost CMS themes. Use whenever the user mentions Ghost themes, Ghost CMS, Handlebars templates (.hbs), Ghost Admin, membership/subscription integration, custom settings, or the content API — even without saying "theme". Trigger on: building a blog theme, creating a Ghost site, editing .hbs templates, member-only content, hero sections, routing (routes.yaml), image optimization, dark mode, search, deploy, gscan validation, JSON-LD/SEO, or any mention of {{ghost_head}}, {{ghost_foot}}, {{#foreach}}, {{#get}}, {{img_url}}, {{asset}}, @custom, @member, or Portal. Also use to modify, extend, or debug an existing theme. Also trigger on Koenig editor cards and .kg-* card styling (kg-image-card, kg-gallery-card, kg-bookmark-card, kg-callout-card, kg-toggle-card, kg-header-card, kg-signup-card), card_assets, cards.min.css, and breakout/wide/full-width card layout.

Ghost Theme Skill

Quick Start

If the user already has a Ghost theme, work with it directly. Read its existing templates, package.json, and build setup. The reference files below apply to any Ghost theme — not just the base template.

If the user wants to create a new theme, copy the base template:

    cp -r <skill-install-path>/base-template/ <theme-name>
    cd <theme-name>
    bun install
    bun run build

Where <skill-install-path> is wherever this skill is installed (e.g. ~/.claude/skills/ghost-theme).

The base template includes: all required HBS files, TypeScript + component CSS build pipeline, ESLint, GitHub Actions (CI + deploy), Docker Compose for local Ghost, and ghost-mcp for AI-driven testing.

After copying, update "name" in package.json to the new theme name.

Then run the one-time setup script, which starts Ghost and moves dotfiles (.mcp.json, .github/) into place:

    bash scripts/setup.sh
    bun run dev

Ghost Admin will be at http://localhost:2368/ghost/. On first run, complete the setup wizard, then go to Settings → Design and activate the theme named dev-theme — that is the mount name in docker-compose.yml, regardless of what you named the theme folder or package.json.

Do not write Ghost theme files from scratch. When creating a new theme, always copy the base template.

Routing

Identify what the user needs, then read only the relevant reference file(s). Most tasks need 1-2 files, not all 12.

When you need to...	Read	Key topics
Choose or create templates	01-template-hierarchy.md	Template lookup order, context data shapes, custom templates, foreach variables
Validate theme for upload	02-required-files.md	GScan errors vs warnings, package.json schema, required helpers
Use Handlebars helpers	03-helper-api.md	{{#get}} filters, {{#foreach}}, {{#has}}, {{#is}}, {{#match}}, {{img_url}}
Add SEO or structured data	04-structured-data.md	JSON-LD per context, OpenGraph/Twitter cards, canonical URLs
Build hero sections or layouts	05-hero-patterns.md	Hero variants, featured carousel, custom templates, responsive images
Integrate members/subscriptions	06-members-integration.md	@member object, Portal data-portal values, content gating, tiers
Configure theme settings	07-custom-settings.md	Setting types, {{#match}}, groups, color/image/text patterns, font vars
Set up or modify the build	08-bun-build.md	build.ts, watch mode, zip workflow, TypeScript, PostCSS
Handle responsive images	09-responsive-images.md	image_sizes, srcset/sizes, format conversion, lazy loading
Configure custom routing	10-routing.md	routes.yaml, collections, channels, data binding
Add translations	11-i18n.md	{{t}} helper, locale files, pluralization, RTL
Add dark mode, search, or styling

Common Workflows

New custom page layout: Read 01 for custom-*.hbs naming + template lookup, 05 for layout patterns, 07 if it needs user-configurable options.

Paid members content gating: Read 06 for {{#has visibility}} and Portal attributes, 01 for post vs page context data.

New collection or site section: Read 10 for routes.yaml syntax, 01 for template resolution, 03 for {{#get}} cross-collection queries.

Image performance: Read 09 for srcset/sizes and format conversion, 02 for image_sizes in package.json.

Local dev + deploy: Read 08 for Docker Compose setup, build pipeline, and GitHub Actions deploy workflow when using the base template.

Carousel, hero, or category grid: Read 13 first — Ghost has no native widget system. The answer is always {{#get}} to query posts/tags + the featured flag or tag metadata as the data source + a JS library (Tiny Slider, Swiper) or CSS scroll snap for interactivity.

Custom homepage with full layout control: Read 13 for the home.hbs + routes: /: home pattern. Read 05 for hero variants, 07 for making sections configurable from Ghost Admin.