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.

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 device loop task in Dot. App Content Studio.
• Settings intervals must be between 60,000 and 43,200,000 milliseconds and use whole-minute multiples.
• 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.
• taskAlias belongs at the top level of Text, Image, and Canvas requests. Do not put it inside 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: confirm that the corresponding API content item exists in the device loop task.

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