Twitch

Purpose

Read and write the user's Twitch channel through the Helix API: channel profile, follower count, live stream status and viewers, past broadcasts and clips, channel title/game updates, clip creation. Use when the user mentions Twitch or their stream.

Tooling

All commands go through bin/twitch.py:

bin/twitch.py auth --client-id abc123xyz                              # verify the token (returns own profile)
bin/twitch.py user --client-id abc123xyz --login someuser             # channel profile (omit --login for own)
bin/twitch.py followers --client-id abc123xyz --broadcaster-id 12345  # follower count + recent followers
bin/twitch.py stream --client-id abc123xyz --user-login someuser      # live now? viewer count, title, game
bin/twitch.py videos --client-id abc123xyz --user-id 12345            # past broadcasts and clips
bin/twitch.py channel-update --client-id abc123xyz --broadcaster-id 12345 --title "New title" --game-id 509658  # confirm first
bin/twitch.py clip-create --client-id abc123xyz --broadcaster-id 12345  # confirm first

The followers, videos, channel-update, and clip-create commands need the numeric channel id: run user first to resolve a login to it.

Auth

• Provider id: twitch (credential is collected as custom.twitch)
• Collection: provider OAuth via the secure credential flow (credentials.request_api_access). Self-serve: register an app in the Twitch Developer Console (the Twitch account needs 2FA enabled; there is no review gate). User tokens come from the authorization code flow at https://id.twitch.tv/oauth2/authorize; app-only tokens come from client credentials at https://id.twitch.tv/oauth2/token.
• Required scopes: user:read:email, channel:read:subscriptions, channel:manage:broadcast, clips:edit, chat:write (request only the scopes the commands you need require)
• Client id: every Helix call needs both Authorization: Bearer and a Client-Id header. The bearer token comes from the stored credential; the client id comes from your app registration and is passed with --client-id on every command.
• Allowed hosts: api.twitch.tv
• Status check: bin/twitch.py auth --client-id <id> (must return "ok": true)

Operating Rules

1. channel-update and clip-create are writes: confirm the exact title/game or the clip request with the user before running, unless standing permission exists.
2. Reading (user, followers, stream, videos) needs no confirmation.
3. Twitch Helix is rate-limited to 800 points per minute on the standard app tier; back off on 429s.
4. There is no "schedule a stream" write endpoint: channel metadata updates are the publish-side surface here.
5. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/twitch.py). Do not print, log, or transmit the token value.

Files

• SKILL.md
• bin/twitch.py

Maturity

🧪 Draft: written from Twitch's public Helix docs via the verified research dossier; not yet live-tested end-to-end.