agentleFS
facebookincubatorfacebookincubator/muse-gadget-sdk/skills/gadget-amazon-echo/SKILL.md

gadget-amazon-echo

Skill2.8k starsChanged 26 days agoApache-2.0View on GitHub

Control Amazon Echo speakers and Alexa-linked smart home devices through Muse Home Link using the community alexa-remote-control script. Covers TTS announcements, volume, media transport, TuneIn/music playback, Alexa routines, and smart-home switching via Alexa text commands. Cloud only: needs a Linux Home Link with internet access, the user's own Amazon login kept in a private file on that Home Link, and Amazon's unofficial Alexa web API. State-changing actions need the user's confirmation.

  • Reads credentials

Trending

More talk lately.thin dataabout the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 13 mentionsNov 2026: 1 mention
Dec 2025Jun 2026Nov 2026
Mentions a month of the facebookincubator/muse-gadget-sdk repository that our weekly crawl found: only 14 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Who's talking about facebookincubator/muse-gadget-sdk

The biggest 5 of 14 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 14

Talked about on GitHub, Bluesky and Hacker News (14 times).

On GitHub · 11

6 more on GitHub

On Hacker News · 1

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 9 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when fresh discovery identifies Amazon Echo devices on the user's Alexa account and the user requests spoken announcements, …

    line 15
  2. Distinctive:

    Never use voice purchasing or Drop In.

    line 33
  3. Very specific:

    When the script renews its cookies, it passes the refresh token to curl as an argument, so other accounts on the same machine can briefly …

    line 35
  4. Very specific:

    Read and follow the Home Link networking and safety rules in ~/docs/devices/home_link.md.

    line 59
  5. Distinctive:

    Every command below runs inside such a block.

    line 102
  6. Very specific:

    Never omit -d (the script falls back to the first Echo) and never use -d ALL unless the user asked for every device.

    line 126
  7. Very specific:

    Before smart-home switching, a routine, a Bluetooth connection, or a textcommand that changes anything, read back the selected Echo, the …

    line 173
  8. Distinctive:

    Before the first switch of any smart plug, identify the attached load with the user and keep a note of it for later requests.

    line 182
  9. Distinctive:

    Never exceed the plug's rated amperage.

    line 189
  10. Distinctive:

    After TTS, confirm audibly or ask the user — the API returns success before the speaker finishes talking.

    line 198
  11. Very specific:

    After volume, wait a few seconds, then read it fresh: rm -f "${TMP:?}/.alexa.volume.<serial>" and run -d "$SEL" -z.

    line 200
  12. Distinctive:

    After plug switching, verify via the Alexa app or by asking the user.

    line 206
  13. Distinctive:

    Do not create, modify, or delete Alexa routines, alarms, or schedules under a control request — those need their own requested scope.

    line 213
  14. Distinctive:

    Do not enable voice purchasing or change payment settings, ever.

    line 215

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Amazon Echo — Alexa Voice Control via CLI

Use this skill when fresh discovery identifies Amazon Echo devices on the user's Alexa account and the user requests spoken announcements, volume or playback control, routine triggers, or smart-home device switching.

Tested with: Echo Dot (2nd generation), Echo Dot (5th generation), Amazon Smart Plug, on amazon.in, 2026-10-04.

Limitations up front

  • This drives Amazon's unofficial cloud device APIs via a community script, not a local protocol. It needs a Linux Home Link (the script is a shell program; an ESP32 Home Link cannot run it) that can reach Amazon over the internet, and it acts as the user's Amazon account.
  • Amazon changes authentication without notice; when it breaks, re-auth is the fix, not a bug in these steps.
  • The script renews its session cookies from the refresh token, but Amazon can stop accepting the token. Expect the user to re-run the login tool periodically.
  • Never use voice purchasing or Drop In. No multi-room changes unless the user explicitly asks.
  • When the script renews its cookies, it passes the refresh token to curl as an argument, so other accounts on the same machine can briefly see it in the process list. Use it only on a Home Link where no untrusted account has a shell.

Identify the Device

  • -a prints friendly names only, and the script matches -d against its cached device list by substring, using the first match. When -d is omitted it picks the first Echo on the account. Names alone are not a safe target — select by the full device-list line (see Workflow).
  • Capability notes by hardware (do not assume; confirm generation from the device list or the Alexa app):
    • Echo Dot 5th gen / Echo 4th gen+: temperature sensor and ultrasound motion detection usable as routine triggers; tap gestures; Matter controller support.
    • Older Dots (e.g. 2nd gen): TTS, volume and transport work; no temperature/motion sensors, no Matter.
  • Smart-home devices (plugs, lights, switches linked to Alexa) usually do not appear in -a. They are driven through the Alexa voice pipeline (textcommand), addressed by their Alexa-app friendly name.

Prerequisites

Read and follow the Home Link networking and safety rules in ~/docs/devices/home_link.md.

On a Linux Home Link (the Muse Linux client):

  • alexa-remote-control.sh installed and executable (a single shell script), plus curl, jq and flock (util-linux). Commands run with a minimal PATH (/usr/local/bin, /usr/bin, /bin and the sbin directories), so install it there or call it by absolute path.
  • Each command runs in a fresh non-interactive shell; exports from an earlier command do not persist. Keep the settings below as export lines in a private env file (mode 0600, owned by the Home Link account) and source it in the same command as every call, e.g. . ~/.config/alexa-remote-control.env && alexa-remote-control.sh ....
  • Region: set AMAZON and ALEXA for the user's store — e.g. amazon.com/alexa.amazon.com (US), amazon.in/alexa.amazon.in (India), amazon.de/alexa.amazon.de (Germany), amazon.co.uk/alexa.amazon.co.uk (UK) — and TTS_LOCALE for the user's language (e.g. en-US, en-IN). The script's built-in defaults are German (amazon.de, de-DE); do not rely on them.
  • Authentication: REFRESH_TOKEN (obtained via alexa-cookie-cli) is the script's only working login, and it avoids storing the Amazon password. The env file is the only place the token is stored: the user runs the login tool and writes the token into it themselves. Never ask for the password, OTP or token in chat, never place them in a command line or log, and never print, copy or search the env file; only source it. If the file or token is missing, explain this setup instead.
  • Point TMP at a private directory (mode 0700) owned by the Home Link account rather than the shared /tmp: the script keeps its cookie jar, device list and volume cache there. The same OS account must run the script every time, or cookie/temp file ownership breaks.
  • One call at a time: the script sends every command through the same $TMP/.alexa.cmd file and reuses its other temp files, and Muse can run commands concurrently. Hold a lock on $TMP/.alexa.lock around every call, including the cache rm and the readback that go with it:

    . ~/.config/alexa-remote-control.env && (
      flock -w 20 9 || { echo 'ERROR: another Alexa call is running'; exit 1; }
      SEL='Kitchen Dot=<deviceType>=<serial>=ECHO'
      alexa-remote-control.sh -d "$SEL" -e vol:30
    ) 9>"${TMP:?}/.alexa.lock"

    Every command below runs inside such a block.

Workflow

  1. Discover fresh: the script reuses its cached device list until it is deleted, so run rm -f "${TMP:?}"/.alexa.devicelist.* then alexa-remote-control.sh -a. Read "$TMP/.alexa.devicelist.txt": one line per device, <name>=<deviceType>=<serial>=<family>. Match the user's device by name and serial; if a device is missing or two lines could be it, stop and ask — do not guess.
  2. Select: use that whole line as the selector, e.g. SEL='Kitchen Dot=<deviceType>=<serial>=ECHO' (write an apostrophe in the name, as in Sam's Echo Dot, as '\''). Before acting, check that both grep -c -- "$SEL" "$TMP/.alexa.devicelist.txt" (how the script matches) and grep -cxF -- "$SEL" "$TMP/.alexa.devicelist.txt" (the exact line) print 1. Stop if either does not, if the name contains = (the script splits the line at the first =), or if the line contains *, ?, [, \, %20 or repeated spaces (the script globs and regex-matches the selector); ask the user to rename the device in the Alexa app. Multi-room groups (family WHA) are out of scope for this selector.
  3. Pass -d "$SEL" on every device action below and on its readback. SEL, like the sourced settings, does not carry over between commands: set it in the same command as each call. Never omit -d (the script falls back to the first Echo) and never use -d ALL unless the user asked for every device. The script echoes serial:<serial> for the device it used; confirm it is the selected one.
  4. TTS: -d "$SEL" -e speak:'<text>'. SSML is accepted. Keep the first test under ten words. SPEAKVOL=<level> raises the volume for the announcement, then restores the level it read beforehand — or NORMALVOL (default 10) if it could not read one — so read the volume fresh afterwards when you set it.
  5. Volume: -d "$SEL" -e vol:<0-100>; verify with a fresh read (see Verify the Result).
  6. Media: -d "$SEL" -e play (or pause, next, prev, shuffle, repeat). TuneIn: -d "$SEL" -r '<station>' or -d "$SEL" -e playmusic:TUNEIN:'<station>'. Amazon Music: -d "$SEL" -e playmusic:AMAZON_MUSIC:'<music>'. playmusic splits its argument at the last :, so leave any : out of the station or music text (Piano Sonata Moonlight, not Piano Sonata: Moonlight).
  7. Smart-home switching: -d "$SEL" -e textcommand:'turn on <friendly name>' (or turn off); Alexa answers on the selected Echo. This is a state-changing action — see Load safety below. Never toggle as a retry; use explicit on/off.
  8. Routines: -d "$SEL" -e automation:'<voice trigger>' runs an Alexa routine, with the selected Echo as its device. The script looks the text up among routines' voice triggers first and only then among routine names, so a routine's name can run a different routine whose trigger is that phrase. Pass only the routine's exact voice trigger, as the user reads it in the Alexa app ("When you say ..."). Without one (a name only, or a routine with no voice trigger), run nothing and ask the user to add a trigger or start it from the Alexa app.
  9. Bluetooth: -d "$SEL" -b list shows paired devices, but with more than one paired device it prints every address next to every name, so the pairs are not reliable. Connect with -d "$SEL" -b <MAC> only when the list has exactly one line; otherwise ask the user to connect from the Alexa app.
  10. Diagnostics: -d "$SEL" -q (queue), -d "$SEL" -n (notifications/alarms); -lastalexa and -lastcommand are account-wide.

Pass text, names and stations as one single-quoted argument (write an embedded ' as '\''). The script inserts text into JSON without full escaping and turns " into ', so keep spoken and command text to plain words and punctuation. Leave out *, ?, [ and \ as well: the script expands unquoted text as file patterns, so * could turn into file names from its working directory.

Confirm before acting

  • Before smart-home switching, a routine, a Bluetooth connection, or a textcommand that changes anything, read back the selected Echo, the exact target and the action (for routines, the trigger phrase), and wait for the user's yes. A yes covers that one action only.
  • TTS, volume and playback on the selected Echo, and read-only queries, need only the user's own request.

Load safety (smart plugs)

  • Before the first switch of any smart plug, identify the attached load with the user and keep a note of it for later requests. Switching cuts power to everything on the plug at once — e.g. a TV + streaming box + set-top box on one extension all lose power together, and a set-top box can take minutes to recover.
  • Loads with motors, heaters, medical devices, or network gear need explicit per-action confirmation, not just first-time identification.
  • Never exceed the plug's rated amperage; adding new devices to the circuit is out of scope for a switching request.
  • Abrupt power cuts can corrupt streaming-box storage over time — prefer software shutdown where the user asks for a full off.

Verify the Result

  • The script's exit code does not show whether Amazon accepted a command; treat any ERROR line or error body in its output as a failure.
  • After TTS, confirm audibly or ask the user — the API returns success before the speaker finishes talking.
  • After volume, wait a few seconds, then read it fresh: rm -f "${TMP:?}/.alexa.volume.<serial>" and run -d "$SEL" -z. The script writes the requested level to that cache file before sending the command, and -z returns the cache for a minute, so without the rm it can confirm a change Amazon rejected. No number in the output means the read failed and the change is unverified.
  • After plug switching, verify via the Alexa app or by asking the user; the script's output alone does not prove the relay changed state.
  • On any auth failure, re-run the login flow before retrying. Do not retry a failed switch blindly.

Limits

  • Do not create, modify, or delete Alexa routines, alarms, or schedules under a control request — those need their own requested scope.
  • Do not enable voice purchasing or change payment settings, ever.
  • textcommand and automation can trigger anything Alexa can do. Use them only for the device control or query the user asked for — never for purchases, calls, messages, Drop In or account settings.
  • The temperature and motion sensors are readable only through Alexa responses and routine triggers, not as direct API values. A textcommand question (e.g. "what is the room temperature") is answered aloud on the Echo; the script does not print the answer, so ask the user what Alexa said or report that the reading is unavailable.

Sources

  • alexa-remote-control — command-line control, device list, speak/volume/textcommand reference; these steps match commit fdea2bc0
  • alexa-remote-control README — environment variables (AMAZON, ALEXA, SPEAKVOL, REFRESH_TOKEN)
  • alexa-cookie-cli — the login tool that produces the refresh token
  • alexa-cookie — cookie/refresh-token generation when Amazon's login checks block plain auth

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.