halo-theme-dev
Provides guidance and templates for building and modifying Halo CMS themes.
Install
mkdir -p .claude/skills/halo-theme-dev && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/11543" && unzip -o skill.zip -d .claude/skills/halo-theme-dev && rm skill.zipInstalls to .claude/skills/halo-theme-dev
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use when creating or modifying a Halo CMS theme, writing Thymeleaf templates, configuring theme.yaml or settings.yaml, calling Finder APIs, using vite-plugin-halo-theme, defining theme settings forms, referencing static assets, implementing halo:comment or halo:footer extension points, defining model annotation fields (AnnotationSetting), adding i18n support, or handling error pages. Always use this skill when the user mentions themes, templates, Thymeleaf, theme configuration, or wants to customize the frontend appearance of a Halo site — even if they do not explicitly say "theme."Key capabilities
- →Create or modify Halo CMS themes
- →Write Thymeleaf templates for frontend rendering
- →Configure `theme.yaml` and `settings.yaml`
- →Call Finder APIs for data querying
- →Use `vite-plugin-halo-theme` for theme development
- →Implement custom extension points like `halo:comment` or `halo:footer`
How it works
The skill guides the creation and modification of Halo CMS themes using Spring Boot and Thymeleaf, covering template writing, configuration, API calls, and static asset management. It emphasizes checking online documentation for current APIs.
Inputs & outputs
When to use halo-theme-dev
- →Creating a new Halo theme
- →Writing Thymeleaf templates for Halo
- →Configuring theme settings forms
- →Implementing custom footer extensions
About this skill
Halo Theme Development
Halo is built on Spring Boot + Spring WebFlux + Thymeleaf. Themes use Thymeleaf templates for frontend page rendering.
Important: Halo's APIs, VO field names, and template variables evolve across versions. Do not rely on training data for specific field names, method signatures, or type structures. When writing code that accesses template variables or calls Finder API methods, always fetch the relevant online doc from the References section below first.
Thymeleaf Quick Reference
Core syntax cheatsheet:
<!-- Output text -->
<h1 th:text="${site.title}"></h1>
<!-- Output unescaped HTML -->
<div th:utext="${post.content.content}"></div>
<!-- Links -->
<a th:href="@{${post.status.permalink}}">Post link</a>
<link rel="stylesheet" th:href="@{/assets/dist/style.css}" />
<!-- Loop -->
<li th:each="post : ${posts.items}" th:text="${post.spec.title}"></li>
<!-- Conditionals -->
<div th:if="${posts.hasNext()}">Next page</div>
<div th:unless="${posts.hasNext()}">Last page</div>
<!-- Local variable -->
<div th:with="menu = ${menuFinder.getPrimary()}">...</div>
<!-- Fragment include -->
<div th:replace="~{fragments/header :: header}"></div>
<!-- Layout reuse: pages pass fragments into a parameterized layout -->
<html th:replace="~{layout :: html(head = null, content = ~{::content})}">
<th:block th:fragment="content"><!-- page body --></th:block>
</html>
<!-- Inline JavaScript -->
<script th:inline="javascript">
var url = '[(${#theme.assets("/dist/main.iife.js")})]';
</script>
Development Workflow
- Create a theme folder under
themes/in the Halo working directory (must matchmetadata.nameintheme.yaml) - Write
theme.yaml(required) andsettings.yaml(optional) - Create template files under
templates/ - Install and activate the theme in Console → Theme Management
- Visit the frontend to verify
Disable Thymeleaf caching during development: set env var SPRING_THYMELEAF_CACHE=false (Docker), or spring.thymeleaf.cache: false in config (source mode).
Starter Templates
The assets/ directory provides two ready-to-use theme templates:
assets/theme-minimal/— Zero-build-tool minimal theme with all 8 template files; ideal for quick prototyping or simple themesassets/theme-vite/— Vite project template withvite-plugin-halo-theme(recommended for new themes); includes partial layout reuse and CSS toolchain
Usage: copy the directory into themes/ in your Halo working directory, ensure the folder name matches metadata.name in theme.yaml, then install and activate in Console.
References Index
| File | Content | When to read |
|---|---|---|
| references/api-changelog.md | High-impact theme API changes by Halo version, with docs routes | Before using version-sensitive APIs or raising spec.requires |
| references/structure-and-config.md | Directory structure, theme.yaml fields, root screenshot, settings.yaml form definition | Creating a theme, configuring theme.yaml/settings.yaml |
| references/vite-plugin.md | vite-plugin-halo-theme integration guide, include/slot template syntax, TailwindCSS integration | Setting up a Vite-based theme (recommended) |
| references/templates.md | Template route mapping, available variables per template | Writing template files |
| references/global-variables.md | Global variables (site, theme, theme.config) and type definitions | Accessing site info or theme setting values |
| references/finder-apis.md | All Finder APIs (postFinder, categoryFinder, tagFinder, menuFinder, singlePageFinder, etc.) | Querying data from any template |
| references/static-resources.md | Static asset reference methods (@{}, #theme.assets()) | Referencing CSS/JS/images in plain HTML themes |
| references/template-tags.md | Custom tags (halo:comment extension point, halo:footer injection) | Integrating comment plugins, injecting footer code |
| references/i18n.md | Internationalization via .properties files, #messages, #locale, frontend i18n injection | Adding multi-language support to a theme |
| references/official-plugins.md | Official plugin integration: pluginFinder.available(), search widget, dark mode color scheme adaptation | Adding search, adapting dark mode for plugin UI |
| references/annotations.md | AnnotationSetting for model custom fields, #annotations utility for reading metadata in templates | Adding custom fields to menu items/posts/categories and using them in templates |
| references/packaging.md | Packaging a theme as a ZIP using @halo-dev/theme-package-cli | Preparing a theme for release or upload |
| references/thymeleaf-tips.md | Halo-specific Thymeleaf best practices: literal substitutions, safe navigation, meta tag rules, permalink syntax | Writing any template file |
When not to use it
- →When relying on training data for specific field names, method signatures, or type structures
- →When the task involves general Spring Boot or Spring WebFlux development unrelated to themes
- →When the task requires using outdated Halo APIs or template variables
Limitations
- →The skill does not rely on training data for specific field names, method signatures, or type structures.
- →The skill requires checking relevant online documentation for current APIs.
- →The skill focuses on themes, templates, and frontend customization.
How it compares
This skill provides a structured workflow and specific guidance for Halo theme development using Thymeleaf, offering a tailored approach compared to general web development or CMS theme creation.
Compared to similar skills
halo-theme-dev side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| halo-theme-dev (this skill) | 0 | 3mo | No flags | Intermediate |
| http-generate | 1 | 7mo | Review | Intermediate |
| generating-api-contracts | 0 | 27d | Review | Advanced |
| android-java | 0 | 4mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
http-generate
spring-ai-alibaba
Generates HTTP request examples for Spring Boot Web interfaces according to task specification and saves them as .http files in module-generate.md directories
generating-api-contracts
jeremylongshore
Generate API contracts and OpenAPI specifications from code or design documents. Use when documenting API contracts and specifications. Trigger with phrases like "generate API contract", "create OpenAPI spec", or "document API contract".
android-java
alinaqi
Android Java development with MVVM, ViewBinding, and Espresso testing
azure-messaging-webpubsub-java
microsoft
Build real-time web applications with Azure Web PubSub SDK for Java. Use when implementing WebSocket-based messaging, live updates, chat applications, or server-to-client push notifications.
paw-webapp-layer
keodubo
Use when creating, changing, auditing, or reviewing PAW Forkd webapp controllers, forms, validators, JSP/JSTL views, i18n bundles, Spring Security routes, CSS/JS, uploads, redirects, MVC tests, REST resources, or SPA static-hosting work across TP1 and TP final.
jsf-ajax
hmislk
>