---
name: trmnl-dashboard-builder
description: Guide a recipient from an idea to a personalized TRMNL e-ink dashboard using their chosen data source. Use when planning, building, or troubleshooting a TRMNL X or other TRMNL dashboard; check existing integrations before proposing a Private Plugin.
metadata:
  version: "1.0"
---

# TRMNL dashboard builder

## Quick start for the recipient

These steps are for Claude Code on your computer or Codex CLI / IDE extension. Choose the assistant you use:

1. Open the folder where you want to work on your dashboard in your coding assistant.
2. Save this complete file, including the YAML information at the top, at the matching path below. Each path starts inside your working folder. Create any missing folders, including the leading dots in `.claude` or `.agents`, and keep the filename exactly `SKILL.md`.

| Assistant | Save the file here | Type this to start |
| --- | --- | --- |
| Claude Code | `.claude/skills/trmnl-dashboard-builder/SKILL.md` | `/trmnl-dashboard-builder` |
| Codex CLI / IDE extension | `.agents/skills/trmnl-dashboard-builder/SKILL.md` | `$trmnl-dashboard-builder` |

3. Start a new assistant session in that same folder, then enter the matching invocation in the assistant's chat prompt. You can add: “I'm new to this; help me decide what to display.” The assistant will guide you one step at a time.

These locations and invocation methods follow the official [Claude Code](https://code.claude.com/docs/en/skills) and [Codex](https://developers.openai.com/codex/skills) documentation. For another compatible assistant, use its documented skill location and invocation method with this same file.

## Start with a friendly conversation

When invoked, start the conversation rather than repeating the installation steps. Begin with: “What would you like to glance at on your TRMNL during a normal day? A rough idea is enough.” If they are unsure, offer two or three relatable examples, such as today's plans, a few personal numbers, or updates they currently check on their phone. Help them describe a useful screen in their own words before discussing how to build it.

Reflect their goal in one sentence, then explain the simplest next step in plain English: “You'd like to see [their goal]. I'll first check whether TRMNL already has a ready-made way to show it.” If the source is unknown, first ask: “Where do you usually look for that information now?” Avoid API, polling, webhook, and template details until the chosen approach needs them.

Adapt to what the recipient has already shared. Ask only unanswered, relevant questions, preferably one at a time, and wait for each answer:

- What information matters most, and what should be visible at a glance?
- Which service, file, feed, or other data source contains it?
- Is TRMNL already set up with an account and working device? Which model do they have?
- How often should the information update, and how much delay is acceptable?

Ask about timezone, units, viewing distance, layout preferences, and technical comfort only when they affect the next decision. Use plain language, explain unfamiliar terms when needed, and give one manageable next step. Offer technical details or code when requested or necessary.

This skill guides an assistant; installing this file does not connect a device or data source. Begin with discovery and a plan. Implement only within the recipient's requested scope.

## Working rules

- Consult current official documentation for the selected approach. Cite relevant links, identify verified facts and their source, and label assumptions or unresolved questions. If documentation is unavailable, say what cannot be verified; do not invent endpoints, limits, device specifications, or account features.
- Prepare a concrete, reviewable proposal before requesting approval for external changes or deployment. State what will change, where data will go, any costs, and how to undo it. Wait for explicit approval covering actions such as creating or editing a plugin, authorizing a service, sending a webhook, changing a playlist, or deploying. Prior approval applies only within its stated scope. Read-only research and local drafts can proceed within the task.
- Never ask for secrets in chat or public files/repositories. Use placeholders in examples. Guide the recipient to enter credentials directly into the documented private configuration or a suitable secret store. Use least-privilege, preferably read-only access; keep local secrets outside version control and redact logs, URLs, screenshots, and examples. Treat webhook URLs containing identifiers as secrets. If exposed, revoke or rotate them.
- Prefer existing capabilities and avoid unnecessary applications, servers, or scripts. Do not configure BYOS (Bring Your Own Server) unless explicitly requested. Do not commit, push, or publish without authorization.

## Workflow

### 1. Confirm prerequisites

Establish account/device setup, connectivity, and the actual model, including whether it is TRMNL X. Verify its dimensions, orientation, supported shades, firmware compatibility, and available refresh settings from current documentation or device settings. Do not apply another model's specifications by default.

For custom work, verify current Private Plugin access requirements, including any Developer entitlement or cost, before recommending an upgrade. Help complete only missing prerequisites; obtain approval before purchases or account changes.

### 2. Choose the simplest supported route

Check the official [integration directory](https://trmnl.com/integrations) first, then relevant [community recipes](https://trmnl.com/recipes). Confirm that a candidate supports the required fields, access method, device, and update cadence. Explain any compromises and review a community recipe's behavior before recommending it.

Use a suitable existing integration when it meets the need. Follow its documented setup and skip custom implementation steps. When existing options cannot meet the requirements, propose a Private Plugin and explain only the applicable data strategy:

- **Polling:** TRMNL fetches a supported endpoint on a schedule. Prefer this when TRMNL can securely reach the source and its authentication and response format are supported. A local-only address is not reachable by the hosted service; do not make private data public as a workaround.
- **Webhook:** An existing trusted sender or automation sends data to TRMNL. Choose this when a push or scheduled sender is simpler or polling is unsuitable. Verify that it can produce TRMNL's required payload, including the `merge_variables` object; a source's native webhook may need transformation. Do not assume a new server is required.

Verify current authentication, supported formats, payload limits, rate limits, and account restrictions for the chosen route. Do not promise real-time display: source updates, plugin data retrieval/rendering, and device wake/playlist refresh are separate schedules. Agree on a supported cadence that balances freshness, battery life, and service limits.

### 3. Plan safe data access

Identify only the fields needed, their types, units, timezone, and update timestamps. Use synthetic or sanitized samples to map source fields to display values. Plan pagination or transformation only if necessary. Define behavior for missing fields, empty results, stale data, and source failures.

Explain which selected data will reach TRMNL and be visible on the physical screen. Keep credentials out of templates and rendered content. If custom logic is necessary, propose the smallest supported addition and its maintenance needs before implementation.

### 4. Design for the actual e-ink screen

Start with a small number of priorities, generous spacing, large readable text, clear labels, and strong contrast. Use the device's supported shades; do not rely on color alone. Avoid animation, hover interactions, tiny text, dense tables, and unnecessary decoration. Include a meaningful data timestamp and an understandable empty or stale state.

For a Private Plugin, explain Liquid as TRMNL's template language: it inserts data into markup that TRMNL renders into a screen image. Prefer documented Framework components and supported layouts. Verify variable paths and filters against the actual payload; do not assume the device runs an interactive web application. Choose editor markup from the appropriate examples rather than copying a standalone HTML wrapper unchanged.

### 5. Prepare configuration, then obtain approval

Present the selected route, field mapping, proposed layout, update schedules, credential storage method, and exact configuration steps with placeholders. Draft only the markup or implementation details needed for the agreed approach. Show the reviewable result and request approval before applying external changes or deploying, as described above.

After approval, guide the recipient through the current integration setup or Private Plugin settings, chosen strategy, secure data configuration, markup, and intended device/playlist assignment. Explain each step and verify its result before continuing.

### 6. Preview and test

Preview with sanitized data in the supported editor or Framework preview, using the actual device's dimensions, orientation, and shades. Test long values, overflow, empty results, missing fields, stale timestamps, and error states. Confirm readability at the intended viewing distance.

With approval for live actions, verify each stage separately: source access, data retrieval or delivery, template variables, generated screen, playlist selection, and the device's next refresh. Confirm actual latency and freshness over a scheduled update cycle. Report what was tested, observed results, and remaining assumptions; a preview alone does not prove device delivery.

### 7. Troubleshoot and hand over

Trace failures in order: source permissions and response, polling reachability or webhook strategy/payload, rate limits and logs, variable paths and template syntax, generated image, then playlist, device connectivity, and refresh timing. Use redacted diagnostics and make one targeted correction at a time. Avoid repeated force-refreshes or faster polling as a substitute for finding the cause.

Finish with the chosen route, where configuration lives, normal update behavior, how to preview or refresh safely, how to pause or revert changes, and how to rotate credentials. State what remains untested without claiming success beyond the evidence.

## Official references

Use these as entry points; follow relevant current documentation rather than treating this skill as a fixed API specification.

- [TRMNL architecture and refresh behavior](https://docs.trmnl.com/go/how-it-works)
- [Private Plugins: prerequisites, polling, and setup](https://help.trmnl.com/en/articles/9510536-private-plugins)
- [Screen templating](https://docs.trmnl.com/go/private-plugins/templates)
- [Webhook strategy](https://docs.trmnl.com/go/private-plugins/webhooks)
- [TRMNL Framework and device previews](https://trmnl.com/framework)
- [Agent Skills format](https://agentskills.io/specification)
- [Claude Code skill loading and invocation](https://code.claude.com/docs/en/skills)
- [Codex skill loading and invocation](https://developers.openai.com/codex/skills)