╭─╮╭──╮
 ╭╯ ╰╯   ╮
 ╰═══════╯
SKILL.md

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
Auth error / 401 Session expired Auto-run sig login app-slack (no user prompt needed), retry
invalid_auth xoxc/xoxd tokens invalid Auto-run sig login app-slack (no user prompt needed), retry
channel_not_found Invalid channel ID/name Check channel exists, use slack_channels.py to find it
not_in_channel Not a member of channel Join the channel first

Workflow Examples

Check unread messages

  1. sig run app-slack -- python scripts/slack_unreads.py
  2. To see only DMs: sig run app-slack -- python scripts/slack_unreads.py --type dm
  3. To see only @mentions: sig run app-slack -- python scripts/slack_unreads.py --mentions-only

Search for messages about a topic

  1. sig run app-slack -- bash -c 'python scripts/slack_search.py --query "deployment issue"'
  2. Filter to a channel: sig run app-slack -- bash -c 'python scripts/slack_search.py --query "deployment" --channel #ops'
  3. Filter by date: sig run app-slack -- bash -c 'python scripts/slack_search.py --query "deployment" --after 2025-01-01 --before 2025-01-31'

Read recent channel history

  1. Find the channel: sig run app-slack -- python scripts/slack_channels.py --limit 20
  2. Get messages: sig run app-slack -- bash -c 'python scripts/slack_history.py --channel #general --limit 1d'
  3. Read a thread: sig run app-slack -- bash -c 'python scripts/slack_threads.py --channel #general --thread-ts 1234567890.123456'

Send a message to someone

  1. Find their DM: sig run app-slack -- python scripts/slack_channels.py --type im
  2. Or send directly: sig run app-slack -- bash -c 'python scripts/slack_send.py --channel @john.smith --message "Hello!"'
  3. Reply in a thread: sig run app-slack -- bash -c 'python scripts/slack_send.py --channel #project --thread-ts 1234567890.123456 --message "Thanks!"'

React to a message

  1. Get channel history to find the message timestamp: sig run app-slack -- bash -c 'python scripts/slack_history.py --channel #general --limit 10'
  2. Add a reaction: sig run app-slack -- bash -c 'python scripts/slack_reactions.py --action add --channel C0123456789 --timestamp 1234567890.123456 --emoji thumbsup'
  3. Remove a reaction: sig run app-slack -- bash -c 'python scripts/slack_reactions.py --action remove --channel C0123456789 --timestamp 1234567890.123456 --emoji thumbsup'