alexa

name	alexa
description	Expose HybridClaw as a custom Alexa skill and prepare guarded Alexa smart-home/device control payloads without exposing Amazon credentials.
user-invocable	true
requires	{"bins":["node"]}
credentials	[{"id":"alexa-ask-skill-id","kind":"header","required":true,"secret_ref":{"source":"store","id":"ALEXA_ASK_SKILL_ID"},"scope":"Alexa Skills Kit applicationId verification for inbound custom skill requests","how_to_obtain":"Create a custom Alexa skill in the Alexa developer console. Set the skill\nid as `ALEXA_ASK_SKILL_ID` through browser admin at\n`/admin/secrets`; if browser admin is unavailable,\nuse `/secret set ALEXA_ASK_SKILL_ID \"amzn1.ask.skill.<uuid>\"` in browser\n`/chat` or TUI; local console fallback:\n`hybridclaw secret set ALEXA_ASK_SKILL_ID \"amzn1.ask.skill.<uuid>\"`.\n"},{"id":"alexa-lwa-client-id","kind":"oauth","required":true,"secret_ref":{"source":"store","id":"ALEXA_LWA_CLIENT_ID"},"scope":"Login with Amazon account linking client id","how_to_obtain":"Configure Login with Amazon account linking for the Alexa skill. Set the\nOAuth client id as `ALEXA_LWA_CLIENT_ID` through browser admin at\n`/admin/secrets`; if browser admin is unavailable,\nuse `/secret set ALEXA_LWA_CLIENT_ID \"amzn1.application-oa2-client.<id>\"`\nin browser `/chat` or TUI; local console fallback:\n`hybridclaw secret set ALEXA_LWA_CLIENT_ID \"amzn1.application-oa2-client.<id>\"`.\n"},{"id":"alexa-lwa-client-secret","kind":"oauth","required":true,"secret_ref":{"source":"store","id":"ALEXA_LWA_CLIENT_SECRET"},"scope":"Login with Amazon account linking client secret","how_to_obtain":"Set the LWA client secret as `ALEXA_LWA_CLIENT_SECRET` through browser\nadmin at the active `/admin/secrets` route; if browser admin is\nunavailable, use `/secret set ALEXA_LWA_CLIENT_SECRET \"<client secret>\"`\nin browser `/chat` or TUI; local console fallback:\n`hybridclaw secret set ALEXA_LWA_CLIENT_SECRET \"<client secret>\"`.\n"},{"id":"alexa-smarthome-refresh-token","kind":"oauth","required":false,"secret_ref":{"source":"store","id":"ALEXA_SMARTHOME_REFRESH_TOKEN"},"scope":"Alexa Smart Home Skill API token refresh","how_to_obtain":"Complete the Smart Home Skill OAuth flow. Set the refresh token as\n`ALEXA_SMARTHOME_REFRESH_TOKEN` through browser admin at\n`/admin/secrets`; if browser admin is unavailable,\nuse `/secret set ALEXA_SMARTHOME_REFRESH_TOKEN \"<refresh token>\"` in\nbrowser `/chat` or TUI; local console fallback:\n`hybridclaw secret set ALEXA_SMARTHOME_REFRESH_TOKEN \"<refresh token>\"`.\n"},{"id":"alexa-smarthome-access-token","kind":"bearer","required":false,"secret_ref":{"source":"store","id":"ALEXA_SMARTHOME_ACCESS_TOKEN"},"scope":"Short-lived Alexa Smart Home Event Gateway bearer token","how_to_obtain":"Mint this from the stored Smart Home refresh token outside the prompt and\nroute it through the SecretRef rail.\n"},{"id":"alexa-refresh-cookie","kind":"header","required":false,"secret_ref":{"source":"store","id":"ALEXA_REFRESH_COOKIE"},"scope":"Opt-in community Alexa Remote / alexapy-compatible session cookie","how_to_obtain":"Only enable the community surface after operator approval. Invoke\n`/alexa set up Echo control for amazon.de and store the cookie` from a\nlocal HybridClaw session so the Alexa auth helper can run Amazon's device\nlogin flow, exchange the captured refresh token, and store the resulting\nfull Cookie header.\n"}]
metadata	{"hybridclaw":{"category":"home-automation","short_description":"ASK custom skill verification plus guarded Alexa smart-home and Alexa Remote planning.","tags":["alexa","ask","smart-home","voice","r21"],"related_roadmap":["R21","R48"],"issue":1117,"stakes_tiers":{"green":"[Truncated]","amber":"[Truncated]","red":"[Truncated]"},"escalation":{"writes":"confirm-each","route":"f14"},"cost_measurement":{"system":"UsageTotals","sub_limit_key":"alexa"}}}

Alexa

Use this skill for Amazon Alexa workflows in two narrow modes:

1. Expose HybridClaw as a custom Alexa skill through the Alexa Skills Kit (ASK).
2. Prepare guarded Alexa-as-device reads and write plans for the official Smart Home Skill API and the opt-in community Alexa Remote / alexapy surface.

Do not use this skill for arbitrary Amazon API calls, shopping account access, or browser automation. Keep all credentials behind SecretRef and use the helper to build bounded payloads instead of hand-writing URLs, headers, cookies, or request bodies.

Safety Rules

1. Validate every inbound ASK request before parsing slots or running an agent bridge. Reject invalid Signature, invalid SignatureCertChainUrl, signing certificates that do not cover echo-api.amazon.com, or timestamp drift of 150 seconds or more.
2. Never persist or echo Login with Amazon access tokens. The request token maps to a HybridClaw operator session outside the prompt through the F13 SecretRef rail.
3. Model output sent back to Alexa must be TTS-safe. Use build-response so markdown, code blocks, and very long URLs are stripped before SSML is built.
4. Path-B reads are green but privacy-sensitive because devices, list contents, routines, and last-command history can reveal household behavior.
5. Path-B writes are amber/red. Announcements, list mutations, device control, and routine triggers require exact F8/F14 approval that names the target room or device and the action.
6. Stop after the first 401, 403, or INVALID_AUTHORIZATION_CREDENTIAL response. Emit or surface event: alexa.relink_required; do not retry-loop.
7. The community cookie path is reverse-engineered and can break when Amazon changes web/API behavior. Treat it as opt-in and operationally brittle.
8. Do not accept Amazon passwords, refresh cookies, LWA tokens, or Smart Home tokens in chat or CLI flags. Store them with hybridclaw secret set ....

Command Contract

Show helper usage:

node skills/alexa/alexa.cjs --help

Validate an inbound ASK request body exactly as received by the HTTPS endpoint:

node skills/alexa/alexa.cjs --format json verify-request \
  --request-body /tmp/alexa-request.json \
  --signature-cert-url "$SIGNATURE_CERT_CHAIN_URL" \
  --signature