slack

Files (4)

• SKILL.md
• _shared.ts · assets/
• socket-listen.ts · assets/
• event-shapes.ts

SKILL.md (first lines)

# Slack skill

This skill lets OrgOps agents act as **Slack apps** using **per-agent tokens** stored in OrgOps **secrets**.

It provides:

- A **Socket Mode** listener (one process per agent) that converts Slack events into OrgOps `channel.event.created` events.
- Outbound Slack delivery by consuming OrgOps events in bridged channels.
- Typed event-shape validators (`event-shapes.ts`) consumed by runner/API validation.

## Secrets

Store secrets under the `slack` package using the `secrets` skill.

Per-agent keys (recommended):

- `SLACK_BOT_TOKEN__<AGENT_NAME>` (xoxb-...)
- `SLACK_APP_TOKEN__<AGENT_NAME>` (xapp-...; required for Socket Mode)

Example:

```bash
node --import tsx skills/secrets/assets/set.ts -- slack SLACK_BOT_TOKEN__worker1 xoxb-...
node --import tsx skills/secrets/assets/set.ts -- slack SLACK_APP_TOKEN__worker1 xapp-...
```

## Slack app setup (minimum)

1. Create a Slack App
2. Enable **Socket Mode**
3. Create an **App-Level Token** with scope: `connections:write` (this is the `xapp-...` token)
4. Add **Bot Token Scopes** (typical v1 set):
   - `chat:write`
   - `channels:read`, `groups:read`, `im:read`, `mpim:read`
   - `channels:history`, `groups:history`, `im:history`, `mpim:history`
   - `im:write`
   - `users:read`
   - `search:read`
   - `files:read` (required for file download helpers)
5. Install the app to the workspace to obtain the `xoxb-...` bot token
6. Subscribe to events (Event Subscriptions):
   - `message.channels`, `message.groups`, `message.im`, `message.mpim`
   - `app_mention`

## Scripts

All scripts accept `--agent <agentName>` and use:

- `SLACK_BOT_TOKEN__<agentName>`
- (listener only) `SLACK_APP_TOKEN__<agentName>`

Agent operating rule:

- Use `events_*` tools only. Do not use Slack CLI helpers for runtime interaction.
- Use `events_emit` for outbound Slack-bound events during execution, then return a final validated event object for the runner.

## Outbound via Events API (bridged channel only)

For agent-to-Slack delivery through a bridged OrgOps channel, emit:

- `message.created` for common text replies
- `channel.command.requested` for explicit Slack Web API commands

Preferred tool call from agents:

```json
{
  "tool": "events_emit",
  "args": {
    "type": "message.created",
    "channelId": "<orgops-bridge-channel-id>",
    "payload": {
      "text": "hello from OrgOps"
    }
  }
}
```

Reply in a Slack thread (tool call example):

```json
{
  "tool": "events_emit",
  "args": {
    "type": "message.created",
    "channelId": "<orgops-bridge-channel-id>",
    "payload": {
      "text": "Thanks — here are examples.",
      "threadTs": "1710000000.000100"
    }
  }
}
```

Explicit command example (`channel.command.requested`):

```json
{
  "tool": "events_emit",
  "args": {
    "type": "channel.command.requested",
    "channelId": "<orgops-bridge-channel-id>",
    "payload": {
      "channel": {
        "provider": "slack",
        "connection": "worker1",
        "workspaceId": "T123",
        "spaceId": "C456"
      },
      "command": {
        "action": "chat.postMessage",
        "payload": {
          "text": "hello via command envelope"
        }
      }
    }
  }
}
```

From camplight/orgops, Apache-2.0.

More from camplight/orgops