Slack Agent Skill

Slack

Purpose

Read and write the user's Slack workspace: list channels, read recent history, post messages, search messages, list users. Use when the user mentions Slack or wants something sent to / found in a Slack channel.

Tooling

All commands go through bin/slack.py:

bin/slack.py auth                                        # verify the connection (auth.test)
bin/slack.py channels                                    # list channels (public + private)
bin/slack.py history --channel C0123456789 --limit 20    # recent messages in a channel
bin/slack.py post --channel C0123456789 --text "hello"    # post a message
bin/slack.py users                                       # list workspace users
bin/slack.py search --query "deploy"                     # search messages (needs search:read on the token)

Channel arguments accept channel IDs (C...). Use channels to resolve a #name to its ID first.

Auth

• Provider id: slack (credential is collected as custom.slack)
• Collection: provider OAuth via the secure credential flow (credentials.request_api_access)
• Required scopes: channels:read, channels:history, groups:read, groups:history, chat:write, users:read
• Granting more scopes: the install requests the minimum above so setup always succeeds, but nothing locks you to that set. Add any bot scopes your Slack app needs (OAuth & Permissions in your app settings), then reconnect: the CLI never checks scopes itself, it calls the API with whatever your token carries and reports Slack's own errors when a scope is missing.
• search:read only exists on user tokens: Slack never grants it to bot tokens, and the provider OAuth install used here issues bot tokens. The search command is included anyway; when the token lacks the scope it exits with exact instructions on what to add instead of a raw error. Requesting search:read as a bot scope makes Slack reject the whole install ("Invalid permissions requested"), so it stays out of the default set.
• Allowed hosts: slack.com
• Status check: bin/slack.py auth (must return "ok": true)

Operating Rules

• post is a write: confirm the exact text and destination channel with the user before sending, unless standing permission to post exists.
• Reading (channels, history, users, search) needs no confirmation.
• Slack rate-limits aggressively on bursts; if a call returns ratelimited, wait the Retry-After seconds and continue. Do not hammer.
• Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/slack.py). Do not print, log, or transmit the token value.

Files

• SKILL.md
• bin/slack.py

Maturity

✅ Live-tested: installed from a raw URL and exercised against the real Slack API (auth, channels, users, history, post all verified; private-channel scopes untestable, this workspace has no private channels).