Dot Skill

What is Dot Skill?

Dot Skill gives AI assistants a consistent way to work with Dot. devices. You can list devices, check status, display text or images, switch content, design Canvas screens, and update device settings without writing every request by hand.

It provides three integration paths:

• Portable Agent Skills for agents that discover SKILL.md files
• A local stdio MCP server with fixed device tools
• An OpenAPI schema for GPT Actions and other OpenAPI-compatible clients

What you can do

• Display text, images, and Canvas layouts
• Give API content a task alias so it is easy to identify in the device task list
• Read battery, Wi-Fi, display, and render status
• Read or update device settings and timezones
• List loop or fixed content tasks
• Switch to the next content item
• Validate a Canvas payload locally before sending it

Integration status

Experimental means the repository includes the portable Skill or MCP configuration, but a platform-specific smoke test has not been completed here.

Requirements

• A Dot. account with at least one device
• A Dot. API key
• Python 3.10 or later for helper scripts or the local MCP server
• pipx or uvx for installing or running the MCP server

Get your API key and device serial number before starting.

Local MCP server

The local server runs on the same machine as your agent over stdio. It reads DOT_API_KEY from the process environment, never accepts the key as a tool argument, and does not provide arbitrary HTTP access.

Install it once:

pipx install git+https://github.com/MindReset/dot_skill.git

Or run it on demand:

uvx --from git+https://github.com/MindReset/dot_skill.git dot-mcp

Set the key in the environment of the process that starts your agent:

export DOT_API_KEY="dot_app_<your_api_key>"

The repository includes ready-to-adapt configuration examples for Claude Code, CodeBuddy, Cursor, VS Code, Kimi Code, Hermes, OpenCode, Gemini CLI, Goose, Trae, MiniMax Code, and DeepSeek Harness.

MCP tools

Read-only tools:

• dot_list_devices
• dot_get_device_status
• dot_get_device_settings
• dot_list_timezones
• dot_list_tasks
• dot_validate_canvas

Device-changing tools:

• dot_update_device_settings
• dot_switch_next_content
• dot_send_text
• dot_send_image
• dot_send_canvas

MCP write requests are sent once without automatic retries. If a network error occurs after a write, check the device status or task list before sending the same content again.

Agent Skill installation

Codex plugin

Add the repository as a Codex marketplace:

codex plugin marketplace add git@github.com:MindReset/dot_skill.git

Then install the plugin:

codex plugin add dot-skill@mindreset-dot-skill

Start a new Codex thread after installation so Codex can load the skills.

npx skills add

Install both skills:

npx skills add https://github.com/MindReset/dot_skill.git

Install only device operations:

npx skills add https://github.com/MindReset/dot_skill.git --skill dot-device-openapi

Install only Canvas design guidance:

npx skills add https://github.com/MindReset/dot_skill.git --skill dot-canvas-designer

The older dot-openapi entry remains as a compatibility router. New installations should use dot-device-openapi and dot-canvas-designer.

OpenAPI integration

Import the schema:

https://raw.githubusercontent.com/MindReset/dot_skill/main/openapi/dot-openapi.yaml

Configure Bearer authentication:

Authorization: Bearer dot_app_<your_api_key>

The schema covers device discovery, status, settings, timezones, task lists, content switching, and Text, Image, and Canvas API content.

Choose the loop or fixed list

All three write APIs accept top-level taskType: "loop" | "fixed"; omitting it selects loop. taskKey is looked up only in the selected list. If omitted, the first matching API item in that list is updated; the other list is not searched.

refreshNow controls immediate display for loop content only. Fixed content follows its times configured in Dot. App. The API does not change those settings or immediately refresh it: even a fixed item currently on screen waits for the next scheduled refresh.

List fixed content first, then use the returned Text API key:

python scripts/list_tasks.py --device-id '{{deviceId}}' --type fixed
python scripts/send_text.py --device-id '{{deviceId}}' --task-type fixed \
  --task-key '{{taskKey}}' --title 'Today'

API and payload limits

• The service rate limit is 10 requests per second.
• Text, Image, and Canvas writes require the matching API content item to already exist in the selected loop or fixed list.
• Settings intervals use whole-minute multiples. Minimums depend on the model and power mode; see Device Settings. The maximum is 43,200,000 milliseconds (12 hours).
• Canvas data is limited to 64 KB; windowData to 128 KB; and layoutFull to 8 KB.
• Canvas layouts allow at most 80 elements and a maximum nesting depth of 16.
• Canvas strings are limited to 4,000 characters.
• Put taskType, taskKey, refreshNow, and taskAlias at the request top level, outside Canvas data.

Errors and troubleshooting

• 401: check that DOT_API_KEY is set in the process environment and that the key is valid.
• 404: check the device serial number and confirm the requested content task exists.
• 429: respect the 10 requests-per-second limit and retry deliberately after the rate window passes.
• Canvas validation errors: run dot_validate_canvas or use send_canvas.py --dry-run before sending.
• Text, Image, or Canvas task errors: use the same taskType for listing and writing, and a taskKey from a matching API item in that list. Omitting taskType selects the loop list.

Helper scripts

The repository includes Python scripts for listing devices, checking status, reading or updating settings, listing tasks, switching content, and sending Text, Image, or Canvas payloads. They read DOT_API_KEY from the environment and use the same client and Canvas validation rules as the MCP server.

Related links

• Get API Key
• Get Device ID
• OpenAPI documentation
• Dot Skill repository
• MCP configuration examples