# Slack

> Read and write Slack: list channels, read history, post messages, search, list users. Trigger phrases: slack, slack channel, post to slack.

- Skill: `anil-matcha/slack` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add anil-matcha/slack`
- Raw SKILL.md: https://api.skillmd.com/api/skills/anil-matcha/slack/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Anil-matcha (https://skillmd.com/u/anil-matcha)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/anil-matcha/slack

---


# 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`:

```bash
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
1. `post` is a write: confirm the exact text and destination channel with the user before sending, unless standing permission to post exists.
2. Reading (channels, history, users, search) needs no confirmation.
3. Slack rate-limits aggressively on bursts; if a call returns `ratelimited`, wait the `Retry-After` seconds and continue. Do not hammer.
4. 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).

