/slack

name: slack
description: 'Interact with Slack — read channels, search messages, check unreads, send messages, manage reactions, and look up users. Use this skill whenever the user mentions Slack, wants to read Slack messages, check unread channels, search Slack conversations, send a Slack message, add reactions, or look up Slack users. Also trigger when the user pastes a Slack message URL, mentions a Slack channel (#channel), or asks about Slack notifications.'

Slack

Read channels, search messages, check unreads, send messages, manage reactions, and look up users via Slack.

Setup (run FIRST — every time, before any operation)

You MUST complete this setup before running any script. Do NOT skip this step.

sig status app-slack 2>&1

Check the JSON output fields `configured` and `valid`:

• **`configured: false`** → run Provider Setup below. Do NOT proceed without completing it.
• **`valid: false` (but configured: true)** → run `sig login app-slack`, then re-check.
• **`valid: true`** → detect proxy (see below), then execute the user's request.

Provider Setup

1. Read `<SKILL_DIR>/references/provider-config.yaml` 2. Append the provider block to `~/.sig/config.yaml` under `providers:` 3. Ask the user: "Do you need a proxy to access this site?" — if yes, add `networkProxy: <url>` under the provider in config.yaml 4. Run `sig login app-slack` (with `--network-proxy <url>` if proxy was specified) 5. Verify: run `sig status app-slack` again — must show `valid: true` before proceeding

Proxy Detection (after provider is valid)

grep -A15 "^\s*app-slack:" ~/.sig/config.yaml | grep networkProxy | awk '{print $2}'

If this outputs a URL, prefix ALL python3 commands with `HTTPS_PROXY=<url> HTTP_PROXY=<url>`. If using socks5, convert to socks5h for python (e.g. `socks5://...` → `socks5h://...`). If empty, no proxy needed.

Running Scripts

All scripts require setup to be completed first (see above).

Scripts Reference

All scripts are in this skill's `scripts/` directory. Run via Bash tool.

| Script | Purpose | | -------------------- | ----------------------------------- | | `slack_channels.py` | List/filter channels | | `slack_history.py` | Get channel/DM message history | | `slack_threads.py` | Get thread replies | | `slack_search.py` | Search messages with filters | | `slack_send.py` | Send message or threaded reply | | `slack_unreads.py` | Get unread messages across channels | | `slack_users.py` | Search users by name/email | | `slack_reactions.py` | Add or remove emoji reactions |

slack_channels.py

--type TYPE           Channel types: public_channel,private_channel,im,mpim (default: public_channel,private_channel)
--sort SORT           Sort by: popularity
--limit N             Max channels (default: 100)
--cursor CURSOR       Pagination cursor from previous response

slack_history.py

--channel ID          Channel ID (#name or @user also work) (required)
--limit LIMIT         Time range (1d, 7d, 30d) or message count (50) (default: 1d)
--cursor CURSOR       Pagination cursor
--include-activity    Include join/leave activity messages

slack_threads.py

--channel ID          Channel ID or #name (required)
--thread-ts TS        Thread parent timestamp (required)
--limit LIMIT         Time range or count (default: 1d)
--cursor CURSOR       Pagination cursor

slack_search.py

--query TEXT          Search query (optional if other filters provided)
--channel ID          Filter to channel
--from USER           Filter by sender (user ID or @name)
--before DATE         Before date (YYYY-MM-DD)
--after DATE          After date (YYYY-MM-DD)
--on DATE             On specific date
--threads-only        Only thread messages
--limit N             Max results (default: 20)
--cursor CURSOR       Pagination cursor

slack_send.py

--channel ID          Channel ID, #name, or @user (required)
--message TEXT        Message content (required)
--thread-ts TS        Reply to thread (optional)
--format FORMAT       text/markdown (default) or text/plain

slack_unreads.py

--type TYPE           Filter: all, dm, group_dm, partner, internal (default: all)
--max-channels N      Max channels to check (default: 50)
--max-messages N      Max messages per channel (default: 10)
--mentions-only       Only channels with @mentions
--summary-only        Channel list without messages

slack_users.py

--query TEXT          Search by name, email, or display name (required)
--limit N             Max results (default: 10)

slack_reactions.py

--action ACTION       "add" or "remove" (required)
--channel ID          Channel ID (required)
--timestamp TS        Message timestamp 1234567890.123456 (required)
--emoji NAME          Emoji name without colons, e.g. thumbsup (required)

Key Concepts

**Channel IDs** — Format `Cxxxxxxxxxx`, but scripts also accept `#channel-name` or `@username` for convenience.

**Thread timestamps** — Format `1234567890.123456`. Used to identify specific messages and as parent references for threaded replies.

**Pagination** — All list endpoints use cursor-based pagination. Pass the `--cursor` value from the previous response to get the next page.

**Team ID** — Some edge APIs require your Slack team ID. To find it: open Slack in a browser, go to `<your-workspace>.slack.com`, open DevTools → Network, and look for requests with `team_id` in the response. Alternatively, run `sig run app-slack -- bash -c 'python -c "import scripts.slack_client as c; import json; client = c.SlackClient.create(); print(client.team_id)"'`.

Error Handling

| Error | Cause | Fix | | ------------------- | ------------------------ | -----------------------------------------