slack-app-setup

## When to Use

USE THIS SKILL WHEN:

- The user says "set up Slack", "connect Slack", "add a Slack workspace", "get you on Slack", or any variant that means _connect this assistant to Slack_.
- A freshly-provisioned assistant needs a Slack bot identity (tokens, scopes, events) configured for the first time.
- The user wants to switch the assistant to a new Slack workspace or rotate its tokens.

DO NOT use this skill for runtime Slack operations (posting, reading channels, triage). That is the separate `slack` skill.

The flow has four user actions: **click**, **install**, **copy tokens**, **verify**. Everything else is pre-baked into the manifest the URL creates.

## Value Classification

| Value     | Type       | Storage method            | Secret? |
| --------- | ---------- | ------------------------- | ------- |
| App Token | Credential | `credential_store` prompt | **Yes** |
| Bot Token | Credential | `credential_store` prompt | **Yes** |

A **User OAuth Token** (`xoxp-...`) is _not_ collected by this skill. It's an optional power-user knob for full-workspace visibility — see [Optional: add a User OAuth Token later](#optional-add-a-user-oauth-token-later) at the end.

## Step 1 — Check existing configuration

Call `credential_store` with `action: "list"` (no other arguments). 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.
- If **exactly one is missing** → resume from the missing step (3a or 3b).
- **Otherwise (both missing)** → continue to Step 2 (default).

An existing `user_token` is never blocking — leave it in place.

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

## Step 2 — Create the Slack app (one click)

Infer the bot identity yourself — do not ask the user to confirm before generating the link.

- **Bot name:** your assigned assistant name. If unset → prompt the user to name you first, then come back.
- **Description:** `Assistant for {guardianName}`, from the current user context / `users/default.md`.

Run the bundled script — inputs are JSON on stdin via a single-quoted heredoc, so apostrophes / quotes / backticks / `$` in the bot name or description pass through verbatim and can never break shell quoting or URL encoding:

```
bash {
  command: "bun run skills/slack-app-setup/scripts/build-manifest-url.ts <<'SLACK_INPUT_END'\n{\"name\": \"<bot_name>\", \"desc\": \"<description>\"}\nSLACK_INPUT_END"
  activity: "to generate the Slack app manifest link"
}
```

The heredoc delimiter `'SLACK_INPUT_END'` is single-quoted on purpose — the shell will not expand anything inside it. Inside the JSON, only `"` and `\` need escaping; apostrophes, dollar signs, and backticks do not.

⚠️ CRITICAL — point of action: **You must run the script.** Do not hand-write the manifest, do not show the user raw YAML or JSON, do not type out a URL from memory. The script is the only source of truth for scopes, events, and Socket Mode settings; anything you write yourself will silently miss pieces and setup will fail downstream.

Output is JSON: `{ "ok": true, "data": { "url": "..." } }`. Extract `data.url`.

⚠️ CRITICAL — point of action: **Render the URL as a markdown link** — `[Click here to create your Slack app](URL)`. Do not paste the raw encoded URL into chat. It is ~1700 characters and will wrap, breaking the click.

Tell the user: _"Click the link, pick your workspace, click **Create**. All scopes, events, and Socket Mode are pre-configured — you don't need to touch anything on the creation page."_

Wait for the user to confirm they clicked Create before moving to Step 3.

## Step 3 — Collect tokens

Slack lands the user on **Basic Information** after Create. The app token lives there; the bot/user tokens live on the **Install App** page.

### Step 3a — App-Level Token (Basic Information page)

Do both of the following in the **same response** — the instruction text and the `credential_store` prompt go out together:

1. Tell the user:

   > Scroll to **App-Level Tokens** → **Generate Token and Scopes** → name it "Socket Mode" → add scope `connections:write` → **Generate**. Copy the token (starts with `xapp-`).
   >
   > **Don't paste it in chat — I'll send you a secure prompt to enter it.**

2. In the same response, call `credential_store` with `action: "prompt"`, `service: "slack_channel"`, `field: "app_token"`, `label: "App-Level Token"`, `placeholder: "xapp-..."`, `description: "Paste the App-Level Token you just generated"`.

⚠️ CRITICAL — point of action: **Fire the `credential_store` prompt in this same response. Do not wait for the user to say "okay I have it" before firing it.** The secure prompt queues silently; the user fills it when they're ready. Waiting for verbal confirmation leaves the user stuck staring at instructions with no input field.

⚠️ CRITICAL — point of action: **Always route the token through `credential_store` prompt.** Do NOT ask the user to paste tokens in chat. Do NOT use `ui_show` for collection. Do NOT call `assistant credentials reveal`. The prompt is the only handler that validates and stores securely.

### Step 3b — Install + Bot Token

Tell the user:

> In the left sidebar → **Install App** → **Install to Workspace** → **Allow**. The page that loads shows your **Bot User OAuth Token** (`xoxb-...`). Copy it.
>
> **Don't paste it in chat — I'll send you a secure prompt to enter it.**

Then collect:

- Call `credential_store` with `action: "prompt"`, `service: "slack_channel"`, `field: "bot_token"`, `label: "Bot User OAuth Token"`, `placeholder: "xoxb-..."`, `description: "From Install App page — the Bot User OAuth Token"`.

> ✓ Checkpoint: After Step 3, the `app_token` and `bot_token` are both in the credential store and the user has confirmed both prompts cam