Aqara Agent

aqara-agent is an official Aqara Home AI Agent skill. It supports natural-language home and space management, device inquiry, device control, device configur...

Security Scan

The skill is internally coherent for controlling an Aqara smart-home account, but it asks users to paste an API key which it will persist to disk and it allows the API base URL to be overridden — both create plausible data-exfiltration/privacy risks and the package claims to be "official" while its source/provenance is unknown.

Purpose & Capability

Name/description match the packaged code and references: the scripts implement an Aqara Open API client, device/scene/automation workflows, and helper tools to save an api key and selected home. There are no unrelated environment variables or unrelated binaries requested. Minor mismatch: the pack labels itself "official" but registry/source metadata and homepage are missing — provenance is not established.

Instruction Scope

Runtime instructions expect the agent to read and write files within the skill (assets/user_account.json, assets/login_reply_prompt.json) and to call the Aqara Open API via the provided Python CLI. That scope aligns with the stated purpose. Important behavioral detail: the agent instructs the user to paste the aqara_api_key into chat and the included save_user_account.py will persist that key to assets/user_account.json — a sensitive, explicit data-write operation. The SKILL.md and references constrain API usage rules; there is no instruction to read files or environment outside the skill root.

Install Mechanism

There is no automated install spec (instruction-only skill with code files). The shipped code requires only the 'requests' package (requirements.txt). No downloads from external untrusted URLs or installation of arbitrary binaries are present.

Credentials

The skill does not request unrelated credentials, which is appropriate. However, it will store an aqara_api_key (user-supplied secret) on disk under assets/user_account.json; this persistent storage is necessary for the skill's function but is a privacy risk. Additionally, the client allows overriding the API base URL via environment (AQARA_OPEN_API_URL) or a field in the same assets file (aqara_open_api_url / open_api_url). That flexibility is useful for local proxies or testing but also means a misconfigured or malicious base URL could receive the stored API key and device data — a possible exfiltration vector if the user points the base URL to an attacker-controlled host. The package does not declare a primary credential in metadata, so users may not realize it stores a secret.

Persistence & Privilege

always:false and the skill does not request elevated system-wide privileges. The skill writes only to its own assets/ directory (assets/user_account.json) and does not attempt to modify other skills or system-wide agent settings.

What to consider before installing

This package implements an Aqara Open API client and will ask you to paste an aqara_api_key which it will save to assets/user_account.json. Before installing: 1) Verify the skill's provenance — it claims to be "official" but has no homepage/source link. 2) Inspect the code (scripts/aqara_open_api.py and save_user_account.py) if you don't trust the author. 3) If you proceed, treat the saved file as sensitive: limit its filesystem permissions and do not paste real production keys into public/shared chats — consider creating a limited/test Aqara account/key first. 4) Do not set AQARA_OPEN_API_URL or the aqara_open_api_url/open_api_url field to an unknown host; only point it to official Aqara endpoints or a trusted proxy, because the skill will send your API key and device data to that URL. 5) If you need to remove access later, delete assets/user_account.json and revoke the API key from Aqara. If you cannot verify the publisher, prefer not to install or to run the scripts in an isolated environment.

Aqara Smart Home AI Agent Skill

Basics

aqara_open_api.py CLI

• Invocation: python3 scripts/aqara_open_api.py <method_name> [json_body].
• Must: first argument equals the exact public method name on AqaraOpenAPI (see bash examples in references/*.md). Forbidden: aliases or shortened names unless a reference documents an equivalent.
• Dispatch: get_* -> no JSON body; post_* -> JSON object (optional, default {}).
• Energy: post_energy_consumption_statistic - route from device_ids only (non-empty -> device API; else position). Fields and NL mapping: references/energy-statistic.md.
• Methods (ground list): get_homes, get_rooms, get_home_devices, get_home_scenes, get_home_automations, post_current_outdoor_weather, post_device_base_info, post_device_status, post_device_control, post_device_firmware_query, post_device_firmware_upgrade, post_device_log, post_execute_scene, post_scene_detail_query, post_create_scene, post_scene_snapshot, post_scene_execution_log, post_device_related_automation_query, post_automation_execution_log, post_automation_switch, post_create_automation, post_energy_consumption_statistic. Forbidden call names not present on AqaraOpenAPI unless a reference adds them.
• post_create_automation and raw_config (non-negotiable): Every call Must send non-empty raw_config in the HTTP body (automation-create.md). Forbidden to send only auxiliary_config or only root-level supplemental conditions / actions without non-empty raw_config.
• post_create_automation first round vs follow-up: First call: non-empty raw_config only; auxiliary_config Must be empty (omit the argument or pass {}). If the response needs config-list matching, use LLMConfigReference as the only source for Step 03 -> auxiliary_config (step-03-parse-config-prompt.md). Second and later calls: Must resend the same non-empty raw_config and attach auxiliary_config (Step 3 supplement). scripts/aqara_open_api.py shallow-merges raw_config and auxiliary_config into one JSON when both are passed.
• Optional env: AQARA_OPEN_HTTP_TIMEOUT (default 60), AQARA_OPEN_API_URL (overrides disk). Optional disk: assets/user_account.json keys aqara_open_api_url or open_api_url (full base, no trailing slash required) when env is unset — requests use {base}/{path} (e.g. homes/query).

Skill Package Layout

Relative to the skill root directory (Cursor project: .cursor/skills/aqara-agent/; other layouts: skills/aqara-agent/). Normative: this file + references/*.md + references/scene-workflow/*.md where scene applies + references/automation-workflow/*.md where automation applies (includes recommend.md for recommend-style automation -> example NL -> create) + references/automation-create-workflow/* for post_create_automation (see references/automation-create.md). Optional README.md (human index only) when present in a pack; Forbidden treat it as overriding SKILL.md.

Path	Purpose
SKILL.md	This document.
README.md	Optional human index in some packs; Forbidden treat as overriding SKILL.md.
assets/login_reply_prompt.json	Locales, official_open_login_url, login_url_policy.
assets/user_account.example.json	Template shape.
assets/user_account.json	Live session (sensitive).
assets/device_control_action_table.csv	Normative attribute / action / value mapping for control and scene slots (devices-control.md, scene workflows).
references/*.md	Per-domain procedures (account, home-space, devices inquiry/control/config, scenes index, automations, energy, weather).
references/scene-workflow/*.md	Scene sub-workflows; enter via references/scene-manage.md. Files (scan): list.md (catalog #catalog-list + #scenes-by-device), execute.md, recommend.md, create.md, snapshot.md, execution-log.md, failure-response.md, appendices.md.
references/automation-workflow/*.md	Automation sub-workflows; enter via references/automation-manage.md. Files (scan): list.md (catalog #catalog-list + by-device #by-device), toggle.md, execution-log.md, failure-response.md, recommend.md (recommend-style automation -> example NL -> create; Forbidden post_automation_recommend_query).
references/automation-create-workflow/	NL -> raw_config -> create; Files (scan): manifest.json, step-01-conditions-actions-extract.md, step-02-cell-info-fill.md, step-03-parse-config-prompt.md.
scripts/aqara_open_api.py	CLI + HTTP client.
scripts/save_user_account.py	Writes aqara_api_key.
scripts/runtime_utils.py	Shared helpers.
scripts/requirements.txt	Dependencies.

Core Workflow

deps -> sign-in -> pick home -> intent -> references/*.md -> summarize

Ground Truth (Binding)

Forbidden stating or implying as factual: homes, rooms, devices, capabilities, attributes, counts, logs, or control outcomes, except from executed skill scripts + real API responses or skill-accepted user input (e.g. pasted aqara_api_key). If that flow has not succeeded, Forbidden any factual claim about those entities.

Forbidden demo-style lists, guessed layouts, synthetic values, fake success after errors/timeouts/missing auth, or prose/JSON mimicking API output without a real response.

Must state missing data and cause (e.g. not signed in, API error), then auth/retry/references/. Forbidden imagined padding.

---

Execute in order:

1. Environment

export AQARA_OPEN_HOST=agent.aqara.com

cd .cursor/skills/aqara-agent   # Cursor project layout (repo root)
# cd skills/aqara-agent         # upstream pack layout
pip install -r scripts/requirements.txt

2. Auth

• Must confirm user_account.json readable/writable before features; host/project rules may require reading it first.
• Must follow references/aqara-account-manage.md (switch-home vs re-login, token save, Step 1 login copy).
• Must read assets/login_reply_prompt.json on every login guidance turn. Must set the user-facing login link to the exact official_open_login_url string (login_url_policy). Forbidden invent Open Platform / sns-auth / client_id / redirect_uri URLs from memory.
• Locale from JSON for the user's language; unknown -> en (fallback_locale / default_locale). Must deliver the single-line login URL per references/aqara-account-manage.md.

user_account.json:

{
  "aqara_api_key": "",
  "updated_at": "",
  "home_id": "",
  "home_name": ""
}

3. Home Management

• Must after saving aqara_api_key run references/home-space-manage.md step 0 immediately (fetch homes; one home -> write; many -> show the complete home list + remind user to choose one, then user picks). Forbidden reply only "send home name" without running fetch or without listing all homes when many.
• Must run save_user_account.py and aqara_open_api.py get_homes as two separate invocations. Forbidden && on one shell line (aqara-account-manage.md step 2, home-space-manage.md step 0).
• Switch home: Must re-fetch homes, show the complete list, remind user to pick one, then persist (home-space-manage.md). Forbidden default to re-login. Must use aqara-account-manage.md login only if the user demands re-login/token rotation or the API signals expired/unauthorized.

4. Intent

Categories: space, device query, device control, device configuration, scene, automation, energy. Multiple intents: Must query before control or configuration, in utterance order.

Intent	AqaraOpenAPI methods (details in reference)	Reference
Space	get_homes, get_rooms	references/home-space-manage.md
Device query	get_home_devices, post_device_status; optional post_device_base_info, post_device_log, post_device_firmware_query (firmware version read)	references/devices-inquiry.md
Device control	post_device_control - immediate only	references/devices-control.md + assets/device_control_action_table.csv. If NL is scheduled / delayed device control (not immediate), use create automation - see Automation row.
Device configuration	post_device_firmware_upgrade - Firmware/OTA only - Firmware-only scope	references/devices-config.md
Scene	get_home_scenes, post_execute_scene, post_create_scene, post_scene_snapshot, post_scene_detail_query, post_scene_execution_log; post_current_outdoor_weather - only Scene recommend workflow step 7 Leaving home before control (references/weather-forecast.md); Forbidden elsewhere. Recommend path uses post_device_control unless Create scene applies. Catalog list + post_scene_detail_query: list.md (#catalog-list, #scenes-by-device)	references/scene-manage.md (index); references/weather-forecast.md; other steps in references/scene-workflow/*.md. If NL is scheduled / delayed catalog scene control (not immediate catalog scene run), use create automation - see Automation row.
Automation	get_home_automations, post_device_related_automation_query, post_automation_switch, post_automation_execution_log, post_create_automation	automation-manage.md (list / toggle / logs / direct create when the user already has an executable rule). Recommend automation (situational help, example sentences, then create): automation-workflow/recommend.md only; Forbidden post_automation_recommend_query. Create automation (including NL classified as scheduled / delayed device control or scheduled / delayed catalog scene control, not immediate post_device_control / post_execute_scene): automation-create.md + automation-create-workflow/. Catalog and by-device: list.md; toggle and logs: same as first column.
Energy	post_energy_consumption_statistic	references/energy-statistic.md

Recommend automation (automation path): If the user wants situational ideas and has not given one create-ready rule sentence, Must run automation-workflow/recommend.md steps 0-5 (scope gate in §0: if neither position nor device, get_rooms + position list only — no examples same turn; else get_rooms, scoped get_home_devices, get_home_scenes, mandatory post_device_status, optional post_device_base_info, optional get_home_automations). Forbidden post_automation_recommend_query and platform "template name" strings as data. User-facing reply: success vs error format and id redaction -> that doc §5 (§5.2: localized lead-in line matching the user's input language + numbered lines 1. through 10. (digit + ASCII period only) on success; on error, detail only, no home/device/position/scene/automation ids). After the user selects or rewrites one example line, Must continue with automation-create.md and post_create_automation (non-empty raw_config on every call; LLMConfigReference handling per that doc and step-03).

5. Route and Summarize

Must open the matching references/ doc, run scripts, summarize from actual output only. Forbidden fabricate success or any home/room/device/state not in script/API output (Ground truth).

Illustrative CLI JSON (Agents Only)

Forbidden paste these raw blocks to end users.

REST shape (skeleton):

{
  "code": 0,
  "message": "",
  "data": {}
}

Error Handling

Situation	Action
Device not found	Must state no match; allowed: short candidate list.
Capability unsupported	Must state unsupported; Forbidden imply success.
Home/room not found	Must state no hit; Must direct next step via references/ (re-fetch or verify home).
Multiple device matches	Must list matches; Must one disambiguation question (room or full name).
Not signed in / empty aqara_api_key	Must login + save per references/aqara-account-manage.md, then homes. MissingAqaraApiKeyError -> same.
No home selected	Must references/home-space-manage.md. No home_id -> homes/query; one home -> auto-write; many -> show full home list + choose one prompt, then home_selection_required.
Bad token / auth	Must re-login / refresh (no secret leak). Forbidden treat home switch as auth failure unless home-list returns auth error. unauthorized or insufficient permissions (or equivalent) -> Must re-login per references/aqara-account-manage.md; Forbidden fake success.
Control path blocked	Must say device found, command not sent.
Firmware / configuration path blocked	Must say device found, upgrade or config action not sent; Must references/devices-config.md.
Other	Must short summary + retry/references/; Forbidden internal URLs or full headers.
Indeterminate	Must use references/ + script output; confirmed bug -> Must file skill issue.
Empty API data	Forbidden invent entities/readings; Must re-run or report failure (Ground truth).
HTTP / network	Forbidden treat as success; Must retry or brief explanation; Forbidden raw stacks.

Notes

1. Forbidden raw IDs in user text (device, position, home_id, ...). Exception: automation_id allowed if server desensitized virtual ID.
2. After layout changes, if match fails: Must re-fetch space + devices (references/home-space-manage.md, references/devices-inquiry.md), retry.
3. User replies: Must conclusion first, then detail; Must <= one clarification question.
4. Session gate: unsigned -> Must end on setup; Forbidden imply control ran.
5. Must run scripts/*.py automatically when required (stricter host policy wins).
6. Account/home change: Must update user_account.json and re-run references/aqara-account-manage.md.
7. Forbidden echo tokens/headers; Must treat user_account.json and caches as sensitive.
8. Multiple fuzzy name hits: Must user confirm.
9. User-visible: Forbidden shell, paths, raw stdout, debug JSON, references/ filenames; Must plain summary.
10. Control OK: Must brief close; Forbidden preemptive hedging; fix only after user reports failure.

Out of Scope

Fully unsupported (no API in this skill; point users to Aqara Home app when relevant):

• Cameras - live view / playback.
• Locks - unlock / lock-unlock.
• Shortcuts (e.g. Siri lists) - Must point to Aqara Home app.
• Weather - general forecasts and Q&A; exception: post_current_outdoor_weather only in recommend.md step 7 Leaving home before control - see weather-forecast.md; Forbidden for Create scene, snapshot, run catalog scene, logs, or any other flow.
• Entertainment - beyond devices-control.md.

Limited to documented workflows (no app-only or undocumented features):

• Scenes - only procedures in scene-manage.md and references/scene-workflow/*.md (e.g. list.md, execute.md, recommend.md, create.md, snapshot.md, execution-log.md, failure-response.md, appendices.md).
• Automations - only procedures in automation-manage.md and references/automation-workflow/*.md (list.md, toggle.md, execution-log.md, failure-response.md, recommend.md for recommend-then-create, plus automation-create.md and references/automation-create-workflow/* for post_create_automation).

When the user asks outside the above: Must say unsupported (or not yet); Must direct to Aqara Home app if the app covers it.