Slack

Slack Operations

Use this skill to read and, with explicit confirmation, write Slack data through the Slack Web API: channels, messages, threads, search, files, and webhook signature verification. This is a tool skill for the Slack platform. Building Slack apps and bots is application development; workspace administration (user provisioning, org-level settings, SSO) lives in the Slack admin console. This skill owns the everyday agent workflow: knowing what was said, finding it later, and posting a reply when a human confirms.

Operating contract

1. Read-only discovery before any mutation. List channels, read history, follow threads, search, and list files freely. The bundled slack-cli script makes reads without writing anything.
2. Confirm the target, scope, and rollback path before acting. Sending a message or replying in a thread changes shared workspace state visible to everyone: it requires an explicit human directive naming the channel, plus --dry-run preview and --yes confirmation through slack-cli. There is no "unsend" for team members who already read it.
3. Respect bounded reads. Slack paginates; never page past what the task needs. slack-cli --limit N caps every listing, and responses summarize records rather than dumping raw payloads.
4. Verify webhooks before trusting them. Any handler that accepts Slack events must verify X-Slack-Signature and X-Slack-Request-Timestamp against the app signing secret, or anyone who can reach the endpoint can forge events. slack-cli webhook verify does this check.
5. Keep evidence bounded. Quote short message excerpts and IDs; never paste full threads, tokens, or file contents into chat.

The slack-cli script

scripts/slack-cli is an agent-first, stdlib-only CLI over the Slack Web API. It covers the full issue scope: messages, channels, threads, search, files, and webhook verification.

slack/scripts/slack-cli --help                          # no token or network needed
slack/scripts/slack-cli --json --limit 10 channels list
slack/scripts/slack-cli --json messages list --channel C12345
slack/scripts/slack-cli --json threads list --channel C12345 --ts 1712345678.000001
slack/scripts/slack-cli --json search messages --query "incident"
slack/scripts/slack-cli --json files list --limit 5
slack/scripts/slack-cli messages send --channel C12345 --text "on it" --dry-run   # preview
slack/scripts/slack-cli messages send --channel C12345 --text "on it" --yes       # confirmed
slack/scripts/slack-cli webhook verify --body-file body.json --signature "v0=..." --timestamp 1712345678

Exit codes: 0 success, 1 API error or failed verification, 2 usage error. Sends are guarded: without --dry-run or --yes the script refuses with exit 1 and never calls the API. Reads are bounded by --limit (default 20, max 100).

Operating loop

1. Scope the workspace surface: which channel(s) are relevant, what the question is (what was said, who said it, when), and whether any action is a mutation.
2. Read with bounds: channels list to find IDs, messages list/threads list for history, search messages for cross-channel discovery. All read-only.
3. Triage the answer: map the question to evidence (thread replies for context, search for the exact phrase, files list for shared artifacts).
4. Act with confirmation: only a human directive to send, previewed with --dry-run and confirmed with --yes.
5. Verify: confirm the posted message ts/channel in the response, or for webhooks confirm the signature check result before trusting the event.

Messages, channels, threads

• Channels (conversations.list): public and private channels, archived state, member counts. Channel IDs (C...) are the stable key for every other call — resolve names to IDs before use.
• Messages (conversations.history): newest-first history in a channel, one page at a time. Message records carry ts (the ID), user, and text. Use --cursor from the response metadata to page deliberately.
• Threads (conversations.replies): replies keyed by the parent ts; the parent message is the first result. Thread replies keep thread_ts set to the parent.
• Sending (chat.postMessage): the only mutation in this skill's surface. Always preview with --dry-run, confirm with --yes, and pass --thread-ts to reply in a thread instead of starting a new message. Verify the returned ts and channel.

Search and files

• Search (search.messages): full-text search across visible history with Slack's search syntax (from:, in:, quoted phrases, before:/after:). Results include the matching channel; total tells you how many matches exist while matches stays bounded by --limit.
• Files (files.list): files shared in the workspace, filterable by channel or user, with permalinks and sizes. Downloading file content is out of scope for the CLI (bounded reads); use it to find the file, then fetch the permalink with an authenticated request when a human asks for the content.

Webhook verification

Slack signs every HTTP request to your event/command/interactivity endpoints. To verify:

1. Take the raw request body (exactly as received — do not re-encode).
2. Check X-Slack-Request-Timestamp is within ~5 minutes of now (replay protection).
3. Compute v0=HMAC_SHA256(signing_secret, "v0:" + timestamp + ":" + body) and compare with X-Slack-Signature using a constant-time comparison.
4. Reject with 401 if the timestamp is stale or the signature mismatches.

slack-cli webhook verify --body-file body.json --signature "v0=..." --timestamp <unix> runs exactly this check against SLACK_WEBHOOK_SECRET (or --secret) and reports a constant-time-verified result. Always verify before trusting event payloads — unverified webhook endpoints accept forged events.

Reference routing

Included artifacts

• scripts/slack-cli: bounded, stdlib-only CLI (messages, channels, threads, search, files, webhook verify; --json; --limit; send gated by --dry-run/--yes).
• tests/test_slack_cli.py: 16 deterministic tests against a stub Slack API, including the mutation gate and the read-only contract.
• references/: dated source index + web API operations reference.
• evals/evals.json: six output-quality evaluation cases for agent runs.

Verification boundary

Hard boundaries

• Never send a message or thread reply without a human directive, --dry-run preview, and --yes confirmation — Slack posts are public, durable, and unreadable-back.
• Never trust an inbound webhook without signature and timestamp verification.
• Never page reads past --limit; never dump full threads, tokens, or file contents into chat.
• This skill operates the Slack Web API. It does not build Slack apps (application development), manage users/org settings (admin console), or cover alternative channels platforms (that is their own tooling).

When not to use

• Building Slack apps or bots (Block Kit, Bolt, slash-command apps, OAuth flow design) — that is application development; see backend-engineering for service design.
• Workspace administration (user provisioning, deprovisioning, org-level settings, SSO/SAML, data exports at the org level) — that is the Slack admin console, not the Web API.
• Other team-chat platforms (Discord, Mattermost, Teams) — each has its own tooling; this skill covers Slack only.
• Company-wide policy on messaging or channel governance — that is organizational policy, not an API operation.