/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
      id as `ALEXA_ASK_SKILL_ID` through browser admin at
      `/admin/secrets`; if browser admin is unavailable,
      use `/secret set ALEXA_ASK_SKILL_ID "amzn1.ask.skill.<uuid>"` in browser
      `/chat` or TUI; local console fallback:
      `hybridclaw secret set ALEXA_ASK_SKILL_ID "amzn1.ask.skill.<uuid>"`.
  - 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
      OAuth client id as `ALEXA_LWA_CLIENT_ID` through browser admin at
      `/admin/secrets`; if browser admin is unavailable,
      use `/secret set ALEXA_LWA_CLIENT_ID "amzn1.application-oa2-client.<id>"`
      in browser `/chat` or TUI; local console fallback:
      `hybridclaw secret set ALEXA_LWA_CLIENT_ID "amzn1.application-oa2-client.<id>"`.
  - 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
      admin at the active `/admin/secrets` route; if browser admin is
      unavailable, use `/secret set ALEXA_LWA_CLIENT_SECRET "<client secret>"`
      in browser `/chat` or TUI; local console fallback:
      `hybridclaw secret set ALEXA_LWA_CLIENT_SECRET "<client secret>"`.
  - 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
      `ALEXA_SMARTHOME_REFRESH_TOKEN` through browser admin at
      `/admin/secrets`; if browser admin is unavailable,
      use `/secret set ALEXA_SMARTHOME_REFRESH_TOKEN "<refresh token>"` in
      browser `/chat` or TUI; local console fallback:
      `hybridclaw secret set ALEXA_SMARTHOME_REFRESH_TOKEN "<refresh token>"`.
  - 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
      route it through the SecretRef rail.
  - 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
      `/alexa set up Echo control for amazon.de and store the cookie` from a
      local HybridClaw session so the Alexa auth helper can run Amazon's device
      login flow, exchange the captured refresh token, and store the resulting
      full Cookie header.
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:
        - ask-verify
        - ask-parse
        - ask-response
        - smarthome-discover
        - smarthome-state
        - devices
        - shopping-list
        - todo-list
        - last-commands
        - dnd-state
      amber:
        - announce
        - shopping-list-add
        - todo-list-add
        - music-play
        - routine-trigger
        - smarthome-turn-on
        - smarthome-turn-off
        - smarthome-brightness
        - smarthome-color
      red:
        - voice-command
        - smarthome-thermostat
        - safety-affecting-routine
    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 b