git:20261025.b80c28f to v1.0.0

---

name: slack-cli

description: >-

Interact with Slack workspaces safely via dedicated Python helper scripts.

Allows reading unread messages, channels, threads, searching messages, sending

messages, and reacting with emojis without direct CLI execution.

---

# 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.

```bash

# 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.

```bash

# 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.

```bash

# 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.

```bash

# 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.).

```bash

# 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.

```bash

# 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).

```bash

# 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.

```bash

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.

```bash

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.

```bash

# 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.