Slack Connector

SKILL.md

---
name: slack-connector
description: "Read, send, search, and manage Slack messages using the user's Slack account. Use when the user wants to read channel messages or DMs, send a message to a channel or person, search Slack for a topic or keyword, post an update to a channel, list channels, or get recent DMs. Keywords: slack, channel, DM, direct message, post, message, send slack, search slack."
metadata:
  polly:
    polly_managed_connector: true
    auth:
      - env: SLACK_USER_TOKEN
        type: oauth2
        integration_id: slack
        description: Slack workspace OAuth access
        user_scopes:
          - channels:read
          - channels:history
          - groups:read
          - groups:history
          - im:read
          - im:history
          - mpim:read
          - mpim:history
          - chat:write
          - users:read
          - users:read.email
          - search:read
          - files:read
          - files:write
    primaryEnv: SLACK_USER_TOKEN
---

# Slack Connector

Interact with Slack on behalf of the user via the Slack Web API.

## First-Time Setup

If Slack is not connected, run:

`manage_auth(action="connect", integration_id="slack", auth_env="SLACK_USER_TOKEN")`

## Auth & Security

- Authentication is managed through Polly + Nango from `metadata.polly.auth`
- Never ask the user to paste tokens in chat
- Never hardcode, print, or log credential values
- If auth is missing/expired, reconnect via:
  `manage_auth(action="connect", integration_id="slack", auth_env="SLACK_USER_TOKEN")`

## Base URL

`https://slack.com/api`

All requests include:

`Authorization: Bearer $SLACK_USER_TOKEN`

## Quick Usage

Test auth:

```bash
curl -sS -H "Authorization: Bearer $SLACK_USER_TOKEN" "https://slack.com/api/auth.test"
```

List channels:

```bash
curl -sS -H "Authorization: Bearer $SLACK_USER_TOKEN" "https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=100"
```

Channel history (replace CHANNEL_ID):

```bash
curl -sS -H "Authorization: Bearer $SLACK_USER_TOKEN" "https://slack.com/api/conversations.history?channel=CHANNEL_ID&limit=20"
```

Search messages:

```bash
curl -sS -H "Authorization: Bearer $SLACK_USER_TOKEN" "https://slack.com/api/search.messages?query=SEARCH_TERM&count=20"
```

Send a message:

```bash
curl -sS -X POST -H "Authorization: Bearer $SLACK_USER_TOKEN" -H "Content-Type: application/json" \
  -d '{"channel":"CHANNEL_ID","text":"Hello!"}' \
  "https://slack.com/api/chat.postMessage"
```

List DM conversations:

```bash
curl -sS -H "Authorization: Bearer $SLACK_USER_TOKEN" "https://slack.com/api/conversations.list?types=im&limit=100"
```

Open a DM with a user (replace USER_ID):

```bash
curl -sS -X POST -H "Authorization: Bearer $SLACK_USER_TOKEN" -H "Content-Type: application/json" \
  -d '{"users":"USER_ID"}' \
  "https://slack.com/api/conversations.open"
```

Look up a user:

```bash
curl -sS -H "Authorization: Bearer $SLACK_USER_TOKEN" "https://slack.com/api/users.info?user=USER_ID"
```

List users:

```bash
curl -sS -H "Authorization: Bearer $SLACK_USER_TOKEN" "https://slack.com/api/users.list?limit=100"
```

Upload a file:

```bash
curl -sS -X POST -H "Authorization: Bearer $SLACK_USER_TOKEN" \
  -F "channels=CHANNEL_ID" -F "file=@/path/to/file" -F "initial_comment=Here's the file" \
  "https://slack.com/api/files.upload"
```

## Workflows

### Read channel messages
1. Resolve channel name to ID via `conversations.list`
2. Fetch messages via `conversations.history`
3. Resolve user IDs to names via `users.info` as needed

### Send a message
- To a channel: `chat.postMessage` with `channel=<channel_id>`
- To a user (DM): open DM via `conversations.open`, then `chat.postMessage`

### Search messages
- Use `search.messages` with a query string
- Returns matches across all channels the user has access to

### Get DMs
1. List DM channels via `conversations.list?types=im`
2. Resolve user IDs to names via `users.info`
3. Fetch messages via `conversations.history`

## Rules
- If auth is required, run `manage_auth` first
- Always resolve channel/user IDs before making history or message calls
- Use `cursor`-based pagination for large result sets
- On error, check the `ok` field and surface the `error` string to the user
- Never log, echo, or expose credential values in any output