# Trmnl

> 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.

- Skill: `usetrmnl/trmnl` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add usetrmnl/trmnl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/usetrmnl/trmnl/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- License: MIT
- Author: usetrmnl (https://skillmd.com/u/usetrmnl)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/usetrmnl/trmnl

---


# 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`](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`](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`](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.

1. **Get your API key:** TRMNL dashboard → any plugin → settings → MCP tab.
2. **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>"}}}` |

3. **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`](https://trmnl.com/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.