Dot Skill

Languages: English | 简体中文 | 日本語

Contribution guide | Support | Security

A portable Agent Skill and local MCP server for AI agents to interact with Dot. devices.

📚 Official Documentation: https://dot.mindreset.tech/docs/service/open/skill

What is Dot Skill?

Dot Skill allows you to:

Control device content: Display text, images, Canvas API layouts, and other content on your Dot. devices
Update scheduled content: Send Text, Image, and Canvas API content to a fixed list and keep its configured display times
Design Canvas layouts: Build windowData cards, dashboards, list views, conditions, and formatting with a dedicated Canvas designer skill
Name API content: Set a task alias for text, image, and Canvas API items so they are easy to identify
Query device status: Get real-time information about device battery, WiFi signal, and current display
Manage devices: List your devices, get device IDs, and switch between content

The repository now splits responsibilities into:

dot-device-openapi: device interaction, API calls, and helper scripts
dot-canvas-designer: Canvas API windowData design and layout guidance
dot-openapi: compatibility router for older installs
dot_mcp: shared Python client, Canvas validator, and local stdio MCP server

Products and display design

Product	Start here
Read Pico	Product docs, hardware resource entry, official demo firmware
Rand/0 (口袋先知)	Product docs, local Display Mode and browser example

See the product guide for hardware summaries and integration boundaries. These product resources do not imply Dot cloud API support. The account and API-key prerequisites below apply to cloud device operations, not reading hardware references or designing content.

The Canvas designer includes content planning and e-paper layout guidance: information hierarchy, typography, image treatment, localization, and empty or stale states.

Prerequisites

A Dot. account with at least one device
An API key from the Dot. App
Python 3.10+ installed locally (for the helper scripts or MCP server)

Installation

Fixed-list updates require version 0.3.0 or later of your installed plugin, skills, and MCP server. Update or reinstall using the original installation method, then restart your agent and MCP server. For GPT Actions or OpenAPI-compatible tools, re-import the latest OpenAPI schema.

Install as a Codex plugin

Add this 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 plugin's skills.

Use with GPT Actions or OpenAPI-compatible agents

Import the OpenAPI schema:

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

Configure Bearer authentication with a Dot. API key:

Authorization: Bearer dot_app_<your_api_key>

Public GPTs or agents that call Dot. APIs should include the Dot. privacy policy and terms:

Privacy Policy: https://dot.mindreset.tech/docs/privacy
Terms of Service: https://dot.mindreset.tech/docs/terms

Use with MCP-compatible agents

The repository includes a local stdio MCP server with fixed Dot tools. Install it with pipx or run it on demand with uvx:

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

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

Set the key in the environment of the agent process:

export DOT_API_KEY="dot_app_<your_api_key>"

Use docs/mcp-configs.md for Claude Code, CodeBuddy, Cursor, VS Code, Kimi Code, Hermes, OpenCode, Gemini CLI, Goose, Trae, MiniMax Code, and DeepSeek Harness configuration examples. Remote MCP is not included.

Install with `npx skills add` (Recommended)

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

Install only the device interaction skill:

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

Install only the Canvas designer skill:

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

Manual Install

mkdir -p ~/.agents/skills
ln -sfn /path/to/dot_skill/skills/dot-device-openapi ~/.agents/skills/dot-device-openapi
ln -sfn /path/to/dot_skill/skills/dot-canvas-designer ~/.agents/skills/dot-canvas-designer

Restart your agent after installation.

Quick Start

Get your API key: Follow the official documentation
Get your device ID: Follow the official documentation
Start using the API: See Device API Reference for endpoints and Canvas windowData Reference for Canvas layout design

Agent Platform Compatibility

Platform	Status	Integration path
Codex	Supported	Repository marketplace at `.agents/plugins/marketplace.json`
OpenAI GPT Actions	Supported via schema	Import `openapi/dot-openapi.yaml` and configure Bearer auth
Claude Code, CodeBuddy, Cursor, VS Code, Kimi Code	Experimental	Use the canonical skills and the local stdio MCP configuration
Hermes, OpenCode, Gemini CLI, Goose	Experimental	Register `dot-mcp` as a local stdio server
Trae, MiniMax Code, DeepSeek Harness	Experimental	MCP-first; use the platform-specific notes in `docs/mcp-configs.md`
Remote MCP and MCP Registry	Planned	No release window is confirmed

API Overview

Endpoint	Method	Description
`/api/authV2/open/devices`	GET	List all your devices
`/api/authV2/open/timezones`	GET	List supported timezones
`/api/authV2/open/device/:deviceId/status`	GET	Get device status
`/api/authV2/open/device/:deviceId/settings`	GET	Get device settings
`/api/authV2/open/device/:deviceId/settings`	POST	Update device settings
`/api/authV2/open/device/:deviceId/next`	POST	Switch to next content
`/api/authV2/open/device/:deviceId/text`	POST	Display text content
`/api/authV2/open/device/:deviceId/image`	POST	Display image content
`/api/authV2/open/device/:deviceId/canvas`	POST	Display canvas content
`/api/authV2/open/device/:deviceId/:taskType/list`	GET	List device tasks

Helper Scripts

The skills/dot-device-openapi/scripts/ directory contains Python helper scripts:

send_text.py: Send text to a device
send_image.py: Send an image to a device
send_canvas.py: Send a Canvas API JSON layout to a device
get_device_status.py: Get current device status
get_device_settings.py: Get device settings
update_device_settings.py: Update device settings
list_devices.py: List all your devices
list_tasks.py: List device loop or fixed tasks
switch_next.py: Switch to the next content

All helper scripts use the shared dot_mcp client and Canvas validator. Run python scripts/sync_bundle.py --check before publishing to detect drift in the portable plugin bundle.

Text, image, and Canvas helper scripts support --task-alias to set the human-readable task name shown in the device task list.

Use --task-type fixed to update a fixed-list item. taskKey selects an item within that list; without it, the first matching API item is updated. Fixed content waits for its next scheduled refresh, even if it is currently displayed or refreshNow is true. Canvas --payload keeps the file's taskType unless an explicit --task-type overrides it. Omitting taskType defaults to loop.

Resources

Device API Reference - Device interaction and endpoint documentation
Canvas windowData Reference - Canvas layout design rules
Canvas Examples - Example Canvas payloads
Authentication - How to authenticate requests
OpenAPI Schema - Importable schema for Actions and OpenAPI-compatible tools
Agent support - Platform status and installation routes
MCP configuration - Local stdio configuration examples
Security Policy - Credential handling and vulnerability reporting
Official Dot. Security Policy - Responsible disclosure process
Support - Issue reporting guidance
Changelog - Release notes

Maintainer Notes

This repository is the public, user-facing skill package for Dot. device control and Canvas design. When Dot Web changes API behavior, keep these surfaces aligned:

openapi/dot-openapi.yaml for OpenAPI-compatible agents and GPT Actions
skills/dot-device-openapi for device interaction scripts and endpoint guidance
skills/dot-canvas-designer for Canvas API payload design rules
plugins/dot-skill for Codex plugin packaging
dot_mcp and pyproject.toml for the local MCP runtime
plugin.json, mcp.json, .claude-plugin, and .codebuddy-plugin for portable plugin metadata
scripts/sync_bundle.py to keep the plugin bundle aligned with canonical skills and OpenAPI content
Dot Web public docs under dot_web_docs

Internal-only Studio V2 implementation, MongoDB migration, and render-debugging workflows belong in dot_internal_skill, not this public package.

License

MIT License - see LICENSE for details.

Navigation Menu

Repository navigation

About

Repository files navigation

Dot Skill

What is Dot Skill?

Products and display design

Prerequisites

Installation

Install as a Codex plugin

Use with GPT Actions or OpenAPI-compatible agents

Use with MCP-compatible agents

Install with `npx skills add` (Recommended)

Manual Install

Quick Start

Agent Platform Compatibility

API Overview

Helper Scripts

Resources

Maintainer Notes

License

About

Contributors

Languages

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.claude-plugin		.claude-plugin
.codebuddy-plugin		.codebuddy-plugin
.github		.github
docs		docs
dot_mcp		dot_mcp
openapi		openapi
plugins/dot-skill		plugins/dot-skill
scripts		scripts
skills		skills
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.ja-JP.md		README.ja-JP.md
README.md		README.md
README.zh-CN.md		README.zh-CN.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
mcp.json		mcp.json
plugin.json		plugin.json
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

Dot Skill

What is Dot Skill?

Products and display design

Prerequisites

Installation

Install as a Codex plugin

Use with GPT Actions or OpenAPI-compatible agents

Use with MCP-compatible agents

Install with npx skills add (Recommended)

Manual Install

Quick Start

Agent Platform Compatibility

API Overview

Helper Scripts

Resources

Maintainer Notes

License

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Contributors

Languages

Install with `npx skills add` (Recommended)