Slack App Setup

Scope

This skill connects an assistant to a Slack workspace: first-time bot identity (tokens, scopes, events), or switching workspaces and rotating tokens. Runtime Slack operations (posting, reading channels, triage) belong to the separate slack skill.

Step 1 — Check existing configuration

Run assistant credentials list --search slack_channel (via the bash tool). Scan the result for entries with service: slack_channel and note which of app_token, bot_token are present.

Then branch:

• If both ✅ → fully configured. Offer to show status or reconfigure. Stop here unless the user wants a reset.
• Otherwise → continue to Step 2.

✓ Checkpoint: You named which of app_token / bot_token are present before branching. Do not skip the assistant credentials list call and guess.

Step 2 — Open the setup wizard

Call ui_show with surface_type: "channel_setup" and data: { channel: "slack" }. This opens the Slack setup wizard in the side panel. The wizard is non-blocking — the tool returns immediately.

⚠️ CRITICAL: Tool call first, announcement second — in the same turn. Do not write any message that says the wizard is open (or is opening) until the ui_show call has returned success earlier in the same turn. A message claiming the wizard is open when the tool was never called shows the user an empty side panel.

After ui_show returns success, tell the user:

I've opened the Slack setup wizard in the side panel. It will walk you through creating a Slack app from a manifest and connecting it — complete the steps there. The wizard will auto-notify me when you close it. If you run into issues along the way, ask me in chat.

Hand-off notification (phones and narrow windows). On phone-sized clients the setup opens on the Contacts page instead of a side drawer, and completing it there cannot auto-notify. The client signals this with a hidden message like [User action on channel_setup surface: moved the slack setup to the Contacts page]. When you receive that hand-off notification, tell the user:

It looks like the setup opened on your Contacts page rather than a side panel — same steps, different spot. When you've finished, come back here and tell me, and I'll verify the connection.

and rely on their confirmation to trigger Step 3 (no wizard-closed notification will arrive).

If the ui_show call fails, do NOT send that message — tell the user the wizard could not be opened and troubleshoot (e.g. no connected client) before retrying.

✓ Checkpoint: The successful ui_show tool result appears earlier in this turn than your announcement. If it does not, the wizard is not open — make the call before claiming it is.

The wizard handles the entire flow: manifest generation, app creation in Slack, and credential storage. The user copies the manifest from the wizard, hands it to Slack's From a manifest option, and Slack returns both tokens at once on Create and Install. Tokens are entered in secure input fields within the wizard and saved directly via the API — they never enter the chat conversation.

⚠️ CRITICAL: Do NOT collect tokens in chat. Do NOT use assistant credentials prompt for Slack setup. Do NOT ask the user to paste tokens into the conversation. The wizard's secure input fields are the only path for credential entry.

Step 3 — Verify completion

When you receive the wizard-closed notification (or the user says they're done, or asks you to check), verify the connection. The notification arrives as a message like [User action on channel_setup surface: closed the slack setup wizard] — closing the wizard drawer sends it automatically, so do not wait for the user to type a confirmation. If the user manually says they're done or asks you to check, proceed with the same verification.

1. Run assistant credentials list --search slack_channel (via the bash tool). Confirm both app_token and bot_token are present.

2. If both are present, fetch the bot identity:

   bash {
     command: "curl -s -X POST https://slack.com/api/auth.test"
     network_mode: "proxied"
     credential_ids: ["slack_channel/bot_token"]
     activity: "to verify bot identity"
   }

   Extract user → botUsername, team → workspace from the JSON response. If ok: false or the call errors, fall back to your bot / your workspace.

3. If either token is missing, tell the user which one is missing. When verification was triggered by the wizard-closed notification, the side panel is no longer open — offer to re-open it and re-run Step 2's ui_show call if they accept. When the user asked manually, the wizard may still be open in the side panel — point them back to it instead of re-opening (a second ui_show over a live wizard resets their progress).

Step 4 — Verify identity (optional)

Load the guardian-verify-setup skill:

• skill_load with skill: "guardian-verify-setup".

If the user wants to skip → continue to Step 5, and let them know they can run it later by saying "verify me on slack".

Step 5 — Report success

⚠️ CRITICAL: Never post the success message with literal {botUsername} or {workspace} in it. Those are placeholders. Run auth.test first (Step 3), substitute real values, then post.

If identity was verified:

Setup complete! ✅ App created ✅ Tokens configured ✅ Connection active ✅ Connection tested

Connected: @<botUsername> in <workspace> Channels: @mention the bot in any channel to add it, or use /invite @<botUsername>. DMs work immediately. Identity: verified

Want full workspace visibility (read every channel you're in, even ones the bot isn't a member of)? Ask me to add a User OAuth Token later.

If identity was skipped → swap the last two lines for:

⬜ Connection tested — say "verify me on slack" to finish later. … Identity: skipped