A repository of Claude Code skills for building Discourse themes and block components:
What’s included
Theme Authoring Skill — covers a comprehensive scope of building a Discourse theme: scaffolding with the discourse_theme CLI, SCSS architecture, viewport library, localization, settings, modifiers, value transformers, icons, and CSS variables. Detailed reference files for icons, variables, and transformers are included separately and can be loaded on demand.
Block Authoring Skill — covers the theme-side of the Blocks API: writing block components with the @block decorator, defining args schemas, rendering blocks into the available core outlets, conditions, container blocks and layout grouping, and integrating theme translations and settings into block args.
Example Theme — a working theme with a custom homepage built with blocks, demonstrating real patterns for outlets, conditions, and layout composition.
About the Blocks API
The Blocks API is Discourse’s new framework for building modular, composable UI components in themes and plugins. Blocks are Glimmer components registered into named outlets — like homepage-blocks, hero-blocks, or sidebar-discovery — and can be conditionally shown based on route, user, viewport, site settings, or plugin availability.
A key strength of the system is that blocks have small, focused scope and consistent patterns. This makes them well-suited for AI-assisted development: a model with the block skill can scaffold a working block component, register it to an outlet, and wire up conditions in a single pass.
The example theme in this repo demonstrates a homepage that adapts based on what plugins and content are available. Here’s what the basic homepage looks like, with a hero block and a featured topic list:
When additional conditions are met (a featured tag is configured, the Discourse Events plugin is active, and the Discourse Leaderboard plugin is available) additional blocks are conditionally rendered into the layout:
Blocks aren’t limited to the homepage. The example theme also uses the sidebar-blocks-outlet to add a Home link, the sidebar-discovery outlet to add category-specific sidebar content, and a category-banner block at the top of category pages:
The blocks inspector on DevTools shows the outlet labels and block identifiers overlaid on the page. This makes it easy to understand the layout structure and debug what’s rendering where:
Using with a design platform MCP
The skills pair well with design platform MCPs (such as the Penpot or Figma MCP). With one connected, Claude can read component specs and design tokens directly from your design files and implement them using the skill’s conventions. It’s a tighter loop between design and code, especially when working from a structured design system.
Fork and adjust
Some conventions in the skills reflect personal preference, like the SCSS folder architecture. You can fork the repo and adjust the skills to match your own workflow and conventions.
Share what you build
Give it a try and let us know how it goes! We’d love to hear how you’re using the skills, what you’ve built with them, and where they fall short. Feedback, corrections, and forks are all welcome.