TRMNL
Everything you need to work on TRMNL. The references in this skill are verbatim copies of the prompts TRMNL's own production AI assistant reads.
Read first, in this order
| # |
Reference |
What it covers |
Lines |
| 1 |
references/agent_prompt.md |
Core rules: data-first hard gate, mandatory workflows, view dimensions, layout system, image dithering, no-custom-styles, no-emojis, common mistakes. This is also what TRMNL's MCP server ships as the connection-level instructions to every external client. |
427 |
| 2 |
references/template_guide.md |
THE design system reference — every framework class, layout pattern, chart code, item component, custom-fields YAML schema. Bundled here so non-MCP users can read it offline; MCP-connected users can also fetch it via the design-system template-guide tool. |
2710 |
| 3 |
references/framework_v3_guide.md |
v3 supplement: chromatic palette, CSS variables, label variants. v3.0.3+ specific. |
230 |
Adding the TRMNL MCP server (optional)
The skill works standalone — agents read the bundled references to write TRMNL-compliant markup locally without ever calling MCP. Adding TRMNL's hosted MCP server unlocks live plugin operations: reading/writing markup on your real plugins, screenshots, merge variable inspection, recipe search.
Get your API key: TRMNL dashboard → any plugin → settings → MCP tab.
Register the server with your agent:
| Agent |
Setup |
| Claude Code |
claude mcp add --transport http trmnl "https://trmnl.com/mcp?api_key=<api-key>" |
| Cursor |
Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project) and add: {"mcpServers": {"trmnl": {"url": "https://trmnl.com/mcp?api_key=<api-key>", "type": "http"}}} — restart Cursor afterward. |
| Codex, Gemini, generic |
Add to your MCP config JSON: {"mcpServers": {"trmnl": {"url": "https://trmnl.com/mcp?api_key=<api-key>"}}} |
Verify: ask your agent to list TRMNL MCP tools — you should see MarkupsReadTool, MarkupsWriteTool, MarkupsScreenshotTool, etc.
Endpoint: POST https://trmnl.com/mcp?api_key=<api-key>. Rate limit: 60 req / 60s.
Tool name mapping
The references reference TRMNL tools two different ways depending on context. Map between them:
| In-app agent (snake_case) |
MCP server (PascalCase + Tool) |
show_integration |
IntegrationsShowTool |
show_merge_variables |
MergeVariablesShowTool |
write_settings |
IntegrationsWriteSettingsTool |
show_logs |
IntegrationsLogsTool |
refresh_data |
IntegrationsRefreshDataTool (async — dispatch via AsyncStartTool) |
read_markup |
MarkupsReadTool |
write_markup |
MarkupsWriteTool |
list_markup_sizes |
MarkupsListSizesTool |
screenshot_markup |
MarkupsScreenshotTool (async — dispatch via AsyncStartTool) |
pull_recipe_markup |
RecipesPullMarkupTool |
| (no in-app equivalent) |
RecipesSearchTool, DesignSystemReferenceTool, DesignSystemTemplateGuideTool, APIEndpointsSearchTool, AsyncStartTool, AsyncResultTool |
If you're calling MCP from outside TRMNL's web app, use the right column. The references use the left column — translate as you go.
What's in-app-only (translate or ignore)
agent_prompt.md was written for TRMNL's in-app AI assistant (the web chat at trmnl.com). A handful of sections are about that web UI specifically and don't apply to external agents (Claude Code, Cursor, Codex, Gemini, Copilot). Translate as you read:
| Reference |
What it says |
What to do externally |
agent_prompt.md:35 |
"NEVER write raw HTML/markup in your chat response" |
Applies only to TRMNL's in-app chat (where markup interferes with the live editor). External agents — show markup in chat freely; users often want to review it before committing. |
agent_prompt.md:71, 208 |
"use ask_user" |
ask_user is an in-app tool. Externally: just ask the user a normal question. |
agent_prompt.md:73 |
"the Self-Correction Workflow (loaded separately in this system prompt)" |
The mandate to screenshot after every write still applies. Iterate; react to overflow signals in the response; look for washed images (missing image-dither) and empty boxes (emoji used). |
agent_prompt.md:95 |
write_markup "broadcasts live update to browser editor" |
Web UI artifact. MarkupsWriteTool writes to the database; there's no editor to update. Ignore the broadcast wording. |
agent_prompt.md:99-102 |
Tools listed: preview_markup, validate_liquid, version_history, ask_user |
None of these exist as external MCP tools. Skip workflow steps that depend on them. |
Everything else in agent_prompt.md applies universally — design rules, e-ink constraints, image dithering, no-custom-styles, no-emojis, the data-first hard gate, spatial proportioning, layout system, charts.
template_guide.md and framework_v3_guide.md are pure design system reference — no in-app artifacts.
NOT for
- The TRMNL REST API for outside-MCP integrations — see the OpenAPI spec at
/api-docs directly.
- TRMNL firmware — different repo.
- Generic Liquid/Shopify/Jekyll questions — TRMNL Liquid has TRMNL-specific filters and merge variables.
How to use the references
These files are LARGE. Read selectively:
- Starting any markup work? →
agent_prompt.md (mandatory workflows section), then jump to relevant template_guide.md section by topic.
- Picked a v3 plugin? → also load
framework_v3_guide.md (color rules differ from v2).
- Need a specific framework class or layout pattern? → search
template_guide.md directly.
Don't load all 3 files at once unless you have to. Each is independently useful.
1---2name: trmnl3description: Use when working on anything TRMNL — building plugins, writing or editing markup, designing layouts using the TRMNL CSS framework, calling the TRMNL MCP server (mcp__trmnl__*), or any task that mentions "trmnl", "e-ink display", "trmnl.com", "TRMNL plugin", "Liquid markup", "image-dither", "title_bar", or screen sizes 800x480 / 800x240 / 400x480 / 400x240. References embed the production prompts TRMNL's external MCP server ships — agent rules, the full design system template guide, and the framework v3 supplement.4license: MIT5---67# TRMNL89Everything you need to work on TRMNL. The references in this skill are **verbatim copies** of the prompts TRMNL's own production AI assistant reads.1011## Read first, in this order1213| # | Reference | What it covers | Lines |14|---|---|---|---|15| 1 | [`references/agent_prompt.md`](references/agent_prompt.md) | Core rules: data-first hard gate, mandatory workflows, view dimensions, layout system, image dithering, no-custom-styles, no-emojis, common mistakes. **This is also what TRMNL's MCP server ships as the connection-level instructions to every external client.** | 427 |16| 2 | [`references/template_guide.md`](references/template_guide.md) | THE design system reference — every framework class, layout pattern, chart code, item component, custom-fields YAML schema. Bundled here so non-MCP users can read it offline; MCP-connected users can also fetch it via the design-system template-guide tool. | 2710 |17| 3 | [`references/framework_v3_guide.md`](references/framework_v3_guide.md) | v3 supplement: chromatic palette, CSS variables, label variants. v3.0.3+ specific. | 230 |1819## Adding the TRMNL MCP server (optional)2021The skill works standalone — agents read the bundled references to write TRMNL-compliant markup locally without ever calling MCP. Adding TRMNL's hosted MCP server unlocks **live plugin operations**: reading/writing markup on your real plugins, screenshots, merge variable inspection, recipe search.22231. **Get your API key:** TRMNL dashboard → any plugin → settings → MCP tab.242. **Register the server with your agent:**2526 | Agent | Setup |27 |---|---|28 | Claude Code | `claude mcp add --transport http trmnl "https://trmnl.com/mcp?api_key=<api-key>"` |29 | Cursor | Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project) and add: `{"mcpServers": {"trmnl": {"url": "https://trmnl.com/mcp?api_key=<api-key>", "type": "http"}}}` — restart Cursor afterward. |30 | Codex, Gemini, generic | Add to your MCP config JSON: `{"mcpServers": {"trmnl": {"url": "https://trmnl.com/mcp?api_key=<api-key>"}}}` |31323. **Verify:** ask your agent to list TRMNL MCP tools — you should see `MarkupsReadTool`, `MarkupsWriteTool`, `MarkupsScreenshotTool`, etc.3334**Endpoint:** `POST https://trmnl.com/mcp?api_key=<api-key>`. Rate limit: 60 req / 60s.3536## Tool name mapping3738The references reference TRMNL tools two different ways depending on context. Map between them:3940| In-app agent (snake_case) | MCP server (PascalCase + Tool) |41|---|---|42| `show_integration` | `IntegrationsShowTool` |43| `show_merge_variables` | `MergeVariablesShowTool` |44| `write_settings` | `IntegrationsWriteSettingsTool` |45| `show_logs` | `IntegrationsLogsTool` |46| `refresh_data` | `IntegrationsRefreshDataTool` (async — dispatch via `AsyncStartTool`) |47| `read_markup` | `MarkupsReadTool` |48| `write_markup` | `MarkupsWriteTool` |49| `list_markup_sizes` | `MarkupsListSizesTool` |50| `screenshot_markup` | `MarkupsScreenshotTool` (async — dispatch via `AsyncStartTool`) |51| `pull_recipe_markup` | `RecipesPullMarkupTool` |52| (no in-app equivalent) | `RecipesSearchTool`, `DesignSystemReferenceTool`, `DesignSystemTemplateGuideTool`, `APIEndpointsSearchTool`, `AsyncStartTool`, `AsyncResultTool` |5354If you're calling MCP from outside TRMNL's web app, use the right column. The references use the left column — translate as you go.5556## What's in-app-only (translate or ignore)5758`agent_prompt.md` was written for TRMNL's *in-app* AI assistant (the web chat at trmnl.com). A handful of sections are about that web UI specifically and don't apply to external agents (Claude Code, Cursor, Codex, Gemini, Copilot). Translate as you read:5960| Reference | What it says | What to do externally |61|---|---|---|62| `agent_prompt.md:35` | "NEVER write raw HTML/markup in your chat response" | Applies only to TRMNL's in-app chat (where markup interferes with the live editor). External agents — show markup in chat freely; users often want to review it before committing. |63| `agent_prompt.md:71, 208` | "use ask_user" | `ask_user` is an in-app tool. Externally: just ask the user a normal question. |64| `agent_prompt.md:73` | "the Self-Correction Workflow (loaded separately in this system prompt)" | The mandate to screenshot after every write still applies. Iterate; react to overflow signals in the response; look for washed images (missing `image-dither`) and empty boxes (emoji used). |65| `agent_prompt.md:95` | `write_markup` "broadcasts live update to browser editor" | Web UI artifact. `MarkupsWriteTool` writes to the database; there's no editor to update. Ignore the broadcast wording. |66| `agent_prompt.md:99-102` | Tools listed: `preview_markup`, `validate_liquid`, `version_history`, `ask_user` | None of these exist as external MCP tools. Skip workflow steps that depend on them. |6768Everything else in `agent_prompt.md` applies universally — design rules, e-ink constraints, image dithering, no-custom-styles, no-emojis, the data-first hard gate, spatial proportioning, layout system, charts.6970`template_guide.md` and `framework_v3_guide.md` are pure design system reference — no in-app artifacts.7172## NOT for7374- The TRMNL **REST API** for outside-MCP integrations — see [the OpenAPI spec at `/api-docs`](https://trmnl.com/api-docs) directly.75- TRMNL **firmware** — different repo.76- Generic Liquid/Shopify/Jekyll questions — TRMNL Liquid has TRMNL-specific filters and merge variables.7778## How to use the references7980These files are LARGE. Read selectively:8182- Starting any markup work? → `agent_prompt.md` (mandatory workflows section), then jump to relevant `template_guide.md` section by topic.83- Picked a v3 plugin? → also load `framework_v3_guide.md` (color rules differ from v2).84- Need a specific framework class or layout pattern? → search `template_guide.md` directly.8586Don't load all 3 files at once unless you have to. Each is independently useful.
usetrmnl