Skip to content
Back to search

skill-email-html-mjml

Claude Code skill — generate cross-client HTML email with MJML. Outlook-safe, Gmail-optimized, WCAG 2.1 AA accessible.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/framix-team--skill-email-html-mjml/badge.svg)](/listings/framix-team--skill-email-html-mjml)

HTML

<a href="/listings/framix-team--skill-email-html-mjml"><img src="/api/listings/framix-team--skill-email-html-mjml/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This is a [Claude Code](https://claude.ai/code) skill. Listed on [skills.sh](https://skills.sh/framix-team/skills/email-html-mjml).

**Option A — npx skills (recommended)**

npx skills add framix-team/skill-email-html-mjml

Requires the [vercel-labs/skills](https://github.com/vercel-labs/skills) CLI. Installs directly into `~/.claude/skills/` and works with Claude Code, opencode, and other compatible agents.

**Option B — Clone and copy**

git clone https://github.com/framix-team/skill-email-html-mjml
cp -r skill-email-html-mjml/email-html-mjml ~/.claude/skills/

**Option C — Download ZIP**

1. Download this repo as a ZIP from GitHub → **Code → Download ZIP** 2. Unzip it 3. Copy the inner `email-html-mjml/` folder to your skills directory:

cp -r skill-email-html-mjml-main/email-html-mjml ~/.claude/skills/

**Verify the install**

ls ~/.claude/skills/email-html-mjml/
# Should show: SKILL.md  compilation.md  mjml-reference.md  components/  assets/

**Claude.ai**

Upload the `email-html-mjml/` folder (zipped) via **Settings → Capabilities → Skills → Upload skill**.

Once installed, Claude will automatically invoke the skill when you ask it to create, generate, or build an HTML email template, or when you ask it to compile MJML or troubleshoot email rendering issues.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 318 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # email-html-mjml — Production-Ready Email Templates for Claude Code
  2. **A Claude Code skill that generates responsive, cross-client HTML email from a single conversation.**
  3. Describe your email. Get back valid MJML source and compiled, production-ready HTML — guaranteed to render in Outlook 2013–365, Gmail (web and app), and Apple Mail without manual table coding, VML hand-authoring, or email client guesswork.
  4. ---
  5. ## The Problem: Email Rendering Is Broken by Design
  6. Every major email client uses a different rendering engine:
  7. - **Outlook 2007–2021** renders HTML with **Microsoft Word** — not a browser
  8. - **Gmail** strips `<head>` CSS and clips messages over **102KB**
  9. - **iOS Mail** and Android stack multi-column layouts when whitespace exists between `inline-block` elements
  10. - **Apple Mail** applies forced dark-mode inversion on light backgrounds
  11. The result: an email that looks correct in a browser can break catastrophically in production. Fixing it requires deep knowledge of **VML injection**, **Ghost Tables**, **CSS inlining**, and client-specific quirks that are rarely documented in one place.
  12. ---
  13. ## The Solution: MJML as a Reliability Framework
  14. This skill uses **MJML 5.x** — not as a convenience layer, but as a **structural reliability framework**. MJML compiles semantic XML into the deeply nested, client-specific table HTML that email clients actually need. The output includes:
  15. - **Ghost Tables** (MSO conditional comments) that constrain layout for Outlook's Word engine while remaining invisible to modern clients
  16. - **Automatic VML injection** for background images in `<mj-section>` and `<mj-hero>`, the only two components where Outlook supports them
  17. - **Hybrid-Fluid column math** — fluid percentage widths for modern clients, fixed Ghost Table widths for Outlook — generated from the same source
  18. Writing this HTML by hand is error-prone and nearly impossible to maintain. MJML makes the correct output the default output.
  19. ---
  20. ## What This Skill Delivers
  21. ### Gmail Clip Prevention
  22. Every template is compiled with `--config.minify=true`, keeping compiled HTML **under Gmail's 102KB clip threshold** — MJML 5's `cssnano` also minifies CSS, so output is smaller than MJML 4's overall.
  23. Note that in MJML 5 minification no longer *removes* whitespace between tags (`htmlnano` collapses each run to a single space). The iOS/Android **column stacking bug** is prevented by the `font-size:0px` MJML emits on the parent `<td>`, not by minification. Pass `--config.minifyOptions '{"collapseWhitespace":"all"}'` for the MJML 4 stripping behavior.
  24. ### Outlook Stability
  25. - **Automatic VML** for background images (section and hero only — the only locations where Outlook generates VML)
  26. - **Font fallback protection** via `<mj-font>`, which wraps `@font-face` imports in MSO conditional comments so Outlook ignores them and uses the system fallback stack instead of Times New Roman
  27. - **Background positioning** restricted to keyword values (`top`, `center`, `bottom`) — pixel values are silently ignored by Outlook
  28. ### Zero-Stacking Guarantee
  29. Multi-column layouts that must stay side-by-side on mobile (social bars, logo rows, icon grids) use `<mj-group>` to prevent stacking. The whitespace-triggered stacking bug is neutralised by the `font-size:0px` MJML sets on the containing cell, which renders any inter-tag whitespace zero-width across iOS Mail and Android Gmail.
  30. ### Head-First Optimization
  31. The `<mj-head>` block is the control center for every template:
  32. - **`<mj-attributes>`** sets global defaults (`<mj-all>`) and named classes (`<mj-class>`) that eliminate repetitive inline styles across sections
  33. - **`<mj-style inline="inline">`** forces Juice CSS inlining for Gmail compatibility — critical layout styles never rely on `<head>` CSS alone
  34. - **`<mj-font>`** imports web fonts with automatic Outlook exclusion
  35. - **`<mj-preview>`** populates inbox preview text
  36. ### Dark Mode Resilience
  37. When dark mode support is required, the skill implements the full pattern: `<meta name="color-scheme" content="light dark">` via `<mj-raw>`, logo swapping via `inline="inline"` style hiding, and `@media (prefers-color-scheme: dark)` overrides in non-inlined `<mj-style>`. Safe neutrals `#121212` and `#F1F1F1` replace pure black and white to prevent jarring forced inversions in Apple Mail.
  38. ### Accessibility (WCAG 2.1 AA)
  39. - Every `<mj-image>` requires `alt` text — enforced at generation time
  40. - `<mj-title>` populates both `<title>` and the `aria-label` on the MJML-generated body wrapper `<div role="article">`
  41. - `lang` on the root `<mjml>` tag flows through to the `<html>` element and body wrapper
  42. - **Heading ARIA roles** are applied via `<mj-html-attributes>` + `css-class` targeting — direct `role` attributes on `<mj-text>` are invalid under strict validation and are never used
  43. ### Templating Engine Support
  44. Dynamic template tags (`{{handlebars}}`, `{% liquid %}`, `{{ jinja }}`) are wrapped in `<mj-raw>` to protect them from the MJML parser. The compiled HTML preserves the tags intact for injection by your ESP (SendGrid, AWS SES, Postmark, etc.).
  45. ### Locked-Down Includes (MJML 5)
  46. `<mj-include>` is disabled by default in MJML 5 — a deliberate security change to prevent path traversal via crafted include paths. Templates that use includes are compiled with `--config.allowIncludes true` and a `--config.includePath` allowlist scoping which directories may be included from. Without this, MJML silently drops the include and logs a warning rather than erroring, so the skill checks compiled output for missing content whenever includes are involved.
  47. ---
  48. ## The Workflow
  49. ```
  50. User request
  51. │
  52. ▼
  53. 1. Gather requirements
  54. Infer email type, brand colors, and layout from context.
  55. Ask only for what is genuinely missing.
  56. │
  57. ▼
  58. 2. Plan layout
  59. Announce structure before writing code:
  60. single-column / 2-col grid / hero+content / etc.
  61. │
  62. ▼
  63. 3. Load component references
  64. Read only the component files needed for this template.
  65. │
  66. ▼
  67. 4. Generate MJML
  68. Complete <mjml> document with full <mj-head>:
  69. mj-attributes, mj-font, mj-title, mj-preview, mj-style
  70. │
  71. ▼
  72. 5. Compile
  73. npx mjml template.mjml -o dist/template.html \
  74. --config.minify=true \
  75. --config.validationLevel=strict
  76. │
  77. ▼
  78. 6. Deliver both files
  79. ├── template.mjml (editable source, version-controllable)
  80. └── dist/template.html (production HTML, send via ESP)
  81. ```
  82. **Output files are always delivered as a pair.** The `.mjml` source is the editable artifact — version-controlled, templating-engine-friendly, safe to modify. The `.html` is the compiled production artifact — minified, table-based, ready to paste into any ESP.
  83. ---
  84. ## Technical Architecture
  85. ### Hybrid-Fluid Design ("Spongy" Layout)
  86. MJML uses a **hybrid** rendering strategy sometimes called "spongy" layout:
  87. - **Modern clients** (Apple Mail, Gmail app, Outlook 365 on Mac): receive fluid percentage widths that respond to the viewport
  88. - **Outlook on Windows** (2013–2021): receives fixed-width Ghost Tables inside MSO conditional comments that constrain the layout to 600px regardless of window size
  89. Both are generated from the same MJML source. The developer writes `<mj-section>` and `<mj-column>` — MJML emits the correct structure for each target.
  90. ### Column Width Math
  91. Column widths are auto-calculated from the default 600px body width:
  92. | Columns | Auto width |
  93. |---------|-----------|
  94. | 1 | 600px (100%) |
  95. | 2 | 300px each (50%) |
  96. | 3 | 200px each (33.33%) |
  97. Override with explicit `width` on `<mj-column>`. Values must sum to 600px or 100%.
  98. ### Document Hierarchy
  99. ```
  100. <mjml lang="en">
  101. └── <mj-head>
  102. │ ├── <mj-title>
  103. │ ├── <mj-preview>
  104. │ ├── <mj-font>
  105. │ ├── <mj-attributes>
  106. │ ├── <mj-style inline="inline"> ← Gmail-safe
  107. │ ├── <mj-style> ← Dark mode / media queries
  108. │ ├── <mj-html-attributes> ← ARIA roles
  109. │ └── <mj-raw> ← Meta tags, template guards
  110. └── <mj-body>
  111. ├── <mj-wrapper> ← Optional: shared border/bg across sections
  112. │ └── <mj-section>
  113. ├── <mj-section> ← Row (background, padding, border)
  114. │ ├── <mj-column> ← Column (width, vertical-align)
  115. │ │ ├── <mj-text>
  116. │ │ ├── <mj-image>
  117. │ │ ├── <mj-button>
  118. │ │ ├── <mj-divider>
  119. │ │ ├── <mj-spacer>
  120. │ │ └── <mj-table>
  121. │ └── <mj-group> ← Prevents mobile stacking
  122. │ └── <mj-column>
  123. ├── <mj-hero> ← Full-bleed hero with VML background
  124. └── <mj-section>
  125. └── <mj-column>
  126. └── <mj-social>
  127. └── <mj-social-element>
  128. ```
  129. Hard constraint: `<mj-section>` cannot be nested inside another `<mj-column>`. All visual content must follow the Section → Column → Content hierarchy.
  130. ---
  131. ## Engineering Rules
  132. | # | Rule | Why It Matters |
  133. |---|------|---------------|
  134. | 1 | All content inside `<mj-column>` inside `<mj-section>` | MJML validation fails otherwise |
  135. | 2 | `<mj-group>` for side-by-side elements on mobile | Prevents iOS/Android column stacking |
  136. | 3 | `<mj-font>` + fallback stack for all web fonts | Blocks Outlook's Times New Roman fallback |
  137. | 4 | `inline="inline"` on `<mj-style>` for critical CSS | Gmail strips `<head>` styles |
  138. | 5 | Always compile with `--config.minify=true` | Fixes stacking bug; stays under 102KB Gmail clip |
  139. | 6 | `alt` on every image; `<mj-title>` always set | WCAG 2.1 AA; screen reader compatibility |
  140. | 7 | `<mj-attributes>` for global defaults | Eliminates repetitive inline styles |
  141. | 8 | `<mj-hero>` for full-bleed backgrounds | VML generated automatically for Outlook |
  142. | 9 | `<mj-raw>` for template engine tags | Protects Handlebars/Liquid from the MJML parser |
  143. ---
  144. ## Known Gotchas
  145. **Vertical-align consistency**: If any `<mj-column>` in a section sets `vertical-align`, every column in that section must also set it explicitly. A single unset column causes inconsistent rendering.
  146. **Background image support**: VML (Outlook-compatible background images) is only generated for `<mj-section>` and `<mj-hero>`. `<mj-column>` background images are not VML-rendered and will not show in Outlook.
  147. **Ending tags**: `<mj-text>`, `<mj-button>`, `<mj-table>`, and `<mj-raw>` are ending tags — their content is raw HTML, not processed by the MJML engine. Do not nest other MJML components inside them.
  148. **Minify and `<` characters**: MJML 4 raised a hard parse error on a bare `<` inside an ending tag; MJML 5 does not, and `Price < 100` now compiles fine. But a *tag-like* `<` (immediately followed by a letter, as in `{{#if a<b}}`) still corrupts the output — silently, at exit `0`. Wrap those in `<!-- htmlmin:ignore -->`; do not escape a template tag as `&lt;`, since the entity reaches your ESP literally.
  149. **Includes silently ignored (MJML 5)**: `<mj-include>` does nothing unless compiled with `--config.allowIncludes true` (plus `--config.includePath` to allowlist directories). MJML logs a warning, not an error, so a template that "compiles fine" may simply be missing the included content.
  150. ---
  151. ## Installation
  152. This is a [Claude Code](https://claude.ai/code) skill. Listed on [skills.sh](https://skills.sh/framix-team/skills/email-html-mjml).
  153. **Option A — npx skills (recommended)**
  154. ```bash
  155. npx skills add framix-team/skill-email-html-mjml
  156. ```
  157. Requires the [vercel-labs/skills](https://github.com/vercel-labs/skills) CLI. Installs directly into `~/.claude/skills/` and works with Claude Code, opencode, and other compatible agents.
  158. **Option B — Clone and copy**
  159. ```bash
  160. git clone https://github.com/framix-team/skill-email-html-mjml
  161. cp -r skill-email-html-mjml/email-html-mjml ~/.claude/skills/
  162. ```
  163. **Option C — Download ZIP**
  164. 1. Download this repo as a ZIP from GitHub → **Code → Download ZIP**
  165. 2. Unzip it
  166. 3. Copy the inner `email-html-mjml/` folder to your skills directory:
  167. ```bash
  168. cp -r skill-email-html-mjml-main/email-html-mjml ~/.claude/skills/
  169. ```
  170. **Verify the install**
  171. ```bash
  172. ls ~/.claude/skills/email-html-mjml/
  173. # Should show: SKILL.md compilation.md mjml-reference.md components/ assets/
  174. ```
  175. **Claude.ai**
  176. Upload the `email-html-mjml/` folder (zipped) via **Settings → Capabilities → Skills → Upload skill**.
  177. Once installed, Claude will automatically invoke the skill when you ask it to create, generate, or build an HTML email template, or when you ask it to compile MJML or troubleshoot email rendering issues.
  178. ---
  179. ## Requirements
  180. - **Claude Code** (Claude Sonnet 4.6 or later recommended)
  181. - **Node.js** ≥ 20 (MJML 5 targets Node LTS 20/22/24; 16/18 are unsupported)
  182. - **MJML** — installed per project, not globally:
  183. ```bash
  184. npm install -D mjml
  185. ```
  186. MJML is never installed globally (`npm install -g mjml` is explicitly avoided). Each project pins its own version. For new projects, pin to the latest stable MJML 5.x release:
  187. ```json
  188. {
  189. "devDependencies": {
  190. "mjml": "^5.4.0"
  191. }
  192. }
  193. ```
  194. ---
  195. ## Repository Structure
  196. ```
  197. skill-email-html-mjml/ ← repo root (GitHub)
  198. ├── README.md ← this file
  199. ├── LICENSE ← MIT
  200. └── email-html-mjml/ ← installable skill folder
  201. ├── SKILL.md ← skill definition and workflow
  202. ├── LICENSE ← MIT (kept alongside the skill for vendoring)
  203. ├── compilation.md ← compilation workflow and error recovery
  204. ├── mjml-reference.md ← MJML architecture, validation, width math
  205. ├── components/
  206. │ ├── head.md ← mj-attributes, mj-font, mj-style, mj-html-attributes
  207. │ ├── layout.md ← mj-section, mj-column, mj-group, mj-wrapper
  208. │ ├── content.md ← mj-text, mj-image, mj-button, mj-divider, mj-table
  209. │ ├── interactive.md ← mj-social, mj-navbar, mj-accordion, mj-carousel
  210. │ └── advanced.md ← mj-hero, mj-raw, mj-include
  211. └── assets/
  212. └── examples/
  213. ├── basic-layout.mjml ← MJML docs basic layout (structural reference)
  214. ├── order-confirmation.mjml ← transactional: tables, Handlebars, mj-include
  215. ├── promo-sale.mjml ← promotional: hero/VML, navbar, social, group
  216. ├── newsletter.mjml ← editorial: full dark-mode pattern, wrapper
  217. └── partials/
  218. └── footer.mjml ← shared partial used by order-confirmation
  219. ```
  220. Component reference files are loaded on-demand — only the files relevant to the current template are read into context. This keeps token usage minimal for simple templates while making the full reference available for complex ones.
  221. ---
  222. ## License
  223. Released under the [MIT License](LICENSE) — free to use, modify, and redistribute, including commercially.
  224. Copyright © 2026 Framix
  225. ---
  226. ## Made by
  227. [Framix](https://www.framix.net/) — Growth Web Presence for Scaling Companies

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.