Slack CLI Helper Skill

This skill enables the agent to safely interact with Slack workspaces using a curated suite of Python scripts.

[!IMPORTANT] Strict Tool Policy: No Direct Raw CLI Fallback Do NOT invoke the raw slackcli executable directly. You must ONLY use the approved Python scripts located in: ./scripts/

This ensures safe operations, eliminates accidental destructive actions (e.g. channel deletion or token exposure), and provides normalized output.

---

Script Suite & Usage Reference

All scripts reside in ./scripts/. Run them using python3 <script-path> [options].

1. get_unread.py - Check Unread Messages

Quickly scan for channels, DMs, or threads with unread messages or mentions.

# Human-readable summary table
python3 ./scripts/get_unread.py

# Machine-readable JSON output
python3 ./scripts/get_unread.py --json

---

2. list_channels.py - Discover Channels and DMs

List public/private channels and conversations you have access to.

# List all channels
python3 ./scripts/list_channels.py

# Filter channels by name
python3 ./scripts/list_channels.py --filter "general"

# Filter by type and limit results
python3 ./scripts/list_channels.py --types public,private --limit 20

---

3. read_channel.py - Read Recent Channel or DM Messages

Fetch recent messages from any channel, private group, or direct message conversation. Automatically formats timestamps and resolves user IDs to human-readable names and handles.

# Read recent messages from a channel by name
python3 ./scripts/read_channel.py questions --limit 10

# Read by channel ID or #channel
python3 ./scripts/read_channel.py "#questions" --limit 20

# Read only top-level channel messages (exclude threaded replies)
python3 ./scripts/read_channel.py questions --exclude-replies

# Programmatic JSON extraction
python3 ./scripts/read_channel.py questions --limit 10 --json

---

4. read_thread.py - Read Message Thread Replies

Inspect an entire conversation thread, displaying the parent message and all subsequent replies chronologically.

# By channel and thread parent timestamp
python3 ./scripts/read_thread.py questions 1791446699.326619

# By Slack permalink URL
python3 ./scripts/read_thread.py --permalink "https://workspace.slack.com/archives/C0123/p1791446699326619"

---

5. search_messages.py - Search Workspace History

Search across messages you have access to using keywords or Slack query operators (after:YYYY-MM-DD, has:link, etc.).

# Search query across conversations
python3 ./scripts/search_messages.py "Thinkpad"

# Search in a specific channel
python3 ./scripts/search_messages.py "deploy" --in general

# Search from a specific user
python3 ./scripts/search_messages.py --from alice --limit 10

---

6. send_message.py - Post Messages & Thread Replies

Send a message to a channel, DM, or thread.

[!TIP] Always use --dry-run to preview and validate the message target before posting to a shared or public channel.

# Preview / Dry run (does not send anything)
python3 ./scripts/send_message.py \
  --recipient "#questions" \
  --message "Hello team" \
  --dry-run

# Post to a channel or user
python3 ./scripts/send_message.py \
  --recipient "#general" \
  --message "Deployment completed."

# Post reply in an existing thread
python3 ./scripts/send_message.py \
  --recipient "#questions" \
  --thread-ts 1791446699.326619 \
  --message "I found the charger!"

---

7. react_message.py - Add or Remove Emoji Reactions

React to any Slack message using emoji names (without colons).

# Add a reaction
python3 ./scripts/react_message.py \
  --channel questions \
  --timestamp 1791446699.326619 \
  --emoji thumbsup

# Remove a reaction
python3 ./scripts/react_message.py \
  --channel questions \
  --timestamp 1791446699.326619 \
  --emoji thumbsup \
  --remove

---

8. get_user_info.py - Look Up User Profiles

Retrieve user profile details, email, timezone, and account status.

python3 ./scripts/get_user_info.py @username
python3 ./scripts/get_user_info.py user@example.com

---

9. edit_message.py - Edit Existing Messages

Replace the text of an existing message you posted.

python3 ./scripts/edit_message.py \
  --channel questions \
  --timestamp 1791446699.326619 \
  --message "Updated message text"

---

10. mark_read.py - Mark Channels as Read

Mark a specific channel or all unread channels as read.

# Mark all unread channels as read
python3 ./scripts/mark_read.py --all

# Mark a specific channel as read up to latest message
python3 ./scripts/mark_read.py questions

# Mark up to a specific timestamp
python3 ./scripts/mark_read.py questions --ts 1791446699.326619

---

Agent Operational Guidelines

1. Verify Before Sending: If instructed to post a message or announcement, run --dry-run first or ask the user to confirm the text and target channel.
2. Name Resolution: The scripts automatically accept human-friendly names (e.g. questions, #questions, @username, or email addresses) as well as Slack IDs (C049..., U09A...).
3. Structured Data: When you need to parse results to make follow-up decisions, append --json to any script.