egregore-labs/egregore / .claude/skills/slack-connect
slack-connect
VerifiedSet up Slack as a notification channel for your Egregore — creates the workspace app, invites the bot, and binds a channel. Use for /slack-connect, 'connect slack', or 'set up slack notifications'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
SKILL.md
View on GitHub---
name: slack-connect
description: "Set up Slack as a notification channel for your Egregore — creates the workspace app, invites the bot, and binds a channel. Use for /slack-connect, 'connect slack', or 'set up slack notifications'."
---
Set up Slack as a notification channel for your Egregore.
Arguments: $ARGUMENTS (none expected)
## When to invoke
**Trigger phrases:**
- "set up slack", "connect slack", "slack-connect"
- "add slack notifications", "slack channel", "notify us on slack"
**Disambiguation:**
- "set up telegram" → `/telegram-connect`
- "set up teams" → `/teams-connect`
- "send a message to slack" → NOT this — use the separate notification
consent protocol in `.claude/context/notification-consent.md`
## What this does
Connects one Slack channel to Egregore notifications using an app the org
creates in its own workspace. After this, everything that plans a group
notification may also resolve Slack as a receiving channel; all resolved
channels are shown before separate dispatch approval.
The privacy contract, stated plainly to the user: **the install screen will
say only "Send messages as @Egregore." The app cannot read messages — the
manifest requests one scope, `chat:write`.** The workspace owns the app and
the token; revoking either cuts Egregore off instantly.
**Works in both modes.** Check which one first:
```bash
bash bin/config-get.sh mode
```
Use the printed value as `{mode}`; quote it in single quotes when you use it in a command, and write any single quote inside the value as `'\''`.
- **local** — the token stays in the gitignored `.env` on this machine and
messages go straight from here to Slack. No Egregore server is in the path.
- **connected** — the token is stored on the org's row so the hosted service
can deliver group notifications from any member's session.
Only Step 5 differs between the modes.
## Step 0: Prerequisites
1. A Slack workspace where this person can install apps. Some workspaces
require admin approval for new apps — if theirs does, the install in
Step 2 turns into a request the admin must approve first.
2. Nothing to install locally. No CLI, no cloud account.
## Step 1: Create the app from the manifest (human, ~1 min)
Show the manifest:
```bash
cat slack-app/manifest.yml
```
(If this instance doesn't carry `slack-app/`, fetch it from the framework repo.)
Guide them: **https://api.slack.com/apps** → **Create New App** →
**From a manifest** → pick their workspace → paste the manifest → **Create**.
## Step 2: Install and copy the bot token (human, 2 clicks + 1 paste)
**Settings → Install App → Install to Workspace** → **Allow**.
Then copy the **Bot User OAuth Token** from the same page. It starts with
`xoxb-`. Validate the prefix when they paste it:
- `xoxb-` — correct.
- `xoxp-` (user token) or `xapp-` (app-level token) — wrong item on the
page; point them back to **Install App → Bot User OAuth Token**.
Do not store it anywhere yet.
## Step 3: Invite the bot to the channel (human, 1 line)
In the target channel: `/invite @Egregore` (or channel name → **Integrations**
→ **Add apps**). With only `chat:write`, the bot can post solely in channels
it is a member of — skipping this yields `not_in_channel` at send time.
## Step 4: Channel ID (human pastes, agent validates)
Ask for the channel ID: channel name → **About** tab → **Channel ID** at the
bottom (or the `/archives/C…` segment of a channel link).
Validate: must match `^[CG][A-Z0-9]{6,}$`. A `D…` id is a DM — not supported;
ask for a channel.
Write the token they pasted in Step 2 to `.env` (gitignored — never commit)
before testing it: append one line, `SLACK_BOT_TOKEN=` followed by the pasted
value, by editing the file directly, never through a shell command, so the
value does not enter the command log. This is the one place the pasted value
is written; the smoke test reads it from there instead of taking it as a typed
argument.
Smoke-test the stored token (no message is sent):
```bash
bash bin/notify.sh slack-auth-test
```
`"ok":true` proves the token and names the workspace — confirm it is the one
they expect. `invalid_auth` here means a mispasted or revoked token; have them
paste it again, rewrite the `SLACK_BOT_TOKEN` line in `.env`, and re-run. Fix
now, not at send time.
## Step 5: Persist
**Local mode** — channel to `.egregore-state.json` (NOT `egregore.json` — the
state file is untracked and shared across worktrees):
```bash
mkdir -p tmp
jq '.slack_channel_id = "<CHANNEL_ID>" | .slack_channel_name = "<#channel-name>"' \
.egregore-state.json > tmp/slack-connect-state.json
```
After `jq` succeeds:
```bash
mv tmp/slack-connect-state.json .egregore-state.json
```
**Connected mode** — store on the org so any member's session can deliver:
```bash
mkdir -p tmp
```
Only read the response with `jq` after the helper succeeds. If it fails, show
its error and stop;
the helper leaves no response file after a failure.
Write the file `tmp/slack-connect-bind.json` with
`{"channel_id":"<CHANNEL_ID>","bot_token":"<TOKEN>","channel_name":"<#channel-name>"}`,
substituting the channel details and the token the user pasted. The helper
reads `EGREGORE_API_KEY` internally.
```bash
bash bin/api-call.sh POST /api/org/slack --auth egregore --json-file tmp/slack-connect-bind.json --out tmp/slack-connect-bind-response.json
```
```bash
jq '.' tmp/slack-connect-bind-response.json
```
Expect `{"status":"connected", …}`.
## Step 6: Verify with separate exact notification consent
Follow `.claude/context/notification-consent.md`. Connecting Slack is not
consent to send a test message. Prepare after configuration is final:
```bash
mkdir -p tmp
```
```bash
bash bin/notify.sh plan group "Slack channel connected — this message reached you through Egregore." > tmp/slack-connect-plan.json
```
```bash
jq -r '.plan_id, .digest' tmp/slack-connect-plan.json
```
Use the printed values as `{plan_id}` and `{digest}`, respectively, for the
notification consent flow. Read the exact preview fields:
```bash
jq -r '.org, .recipient, .channels, .deliveries, .message' tmp/slack-connect-plan.json
```
Show every resolved receiving channel—potentially Telegram, Teams, and
Slack—and the exact message in a dedicated Send / Edit / Cancel checkpoint.
Only dispatch after Send is selected for that preview.
## Troubleshooting quick table
| Symptom | Cause → fix |
|---|---|
| `invalid_auth` | Wrong, revoked, or other-workspace token → Step 2, re-copy from Install App |
| `not_in_channel` | Bot not invited to the channel → Step 3 |
| `channel_not_found` | Wrong channel ID, or a private channel the bot isn't in → Step 4 / invite it |
| `missing_scope` | App not created from the manifest → recreate from Step 1, reinstall |
| `account_inactive` | App was uninstalled from the workspace → reinstall |
| `ratelimited` | Transient — retried automatically |
| Install becomes an approval request | Workspace requires admin approval → the admin approves, then continue |
| Local plan omits slack from channels | Half-configured: `SLACK_BOT_TOKEN` missing from `.env` or `slack_channel_id` missing from `.egregore-state.json` |
## After
Emit telemetry (fire-and-forget):
```bash
bash bin/telemetry.sh emit "slack-connect" '{"command":"slack-connect"}' 2>/dev/null &
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |