Step 6: Verification round-trip

User sends @ hello in the channel from Step 2.

• Reply within 10s → success. Move to Step 7.
• Silence → run /slack-channel:install doctor to diagnose, then

/slack-channel:install repair to fix.

Step 7: Optional next steps

Ask the user if they want any of these:

Mode: doctor

Health check an existing install. Reports a structured pass/fail per check,

no mutations. Suggests /slack-channel:install repair if fixable issues

are found.

Doctor dependencies

The doctor checks below shell out to curl and jq. curl is preinstalled

on virtually every dev system; jq may not be. Verify before running:

command -v curl >/dev/null && command -v jq >/dev/null || echo "Install jq: brew install jq  (macOS)  |  sudo apt install jq  (Debian/Ubuntu)"

The checks also need $SLACKBOTTOKEN and $SLACKAPPTOKEN in the

environment. Load them from the user's .env before running any check

that references them:

set -a; . ~/.claude/channels/slack/.env; set +a

If the user prefers not to export the tokens (some shells leak env to

child processes / process listings), substitute the literal token values

inline — the doctor commands tolerate either form.

Checks

Run all in order:

1. State directory exists: ~/.claude/channels/slack/ is a directory with mode 0700.
2. .env exists, is mode 0600, owned by current user.
3. .env contains both tokens with valid prefixes (xoxb- and xapp-).
4. Bot token is live: curl -s -H "Authorization: Bearer $SLACKBOTTOKEN" https://slack.com/api/auth.test | jq -e '.ok == true'. Reports the botid and team if live; "invalidauth" / "tokenrevoked" / "accountinactive" if not.
5. App token has connections:write: curl -s -X POST -H "Authorization: Bearer $SLACKAPPTOKEN" https://slack.com/api/apps.connections.open | jq -e '.ok == true and (.url | startswith("wss://"))'. Expects ok: true and a wss:// URL. Failure modes: "notauthed" (token missing), "missingscope" (token lacks connections:write), "token_revoked" (regenerate).
6. access.json exists, is mode 0600, parses as valid JSON: [ -f ~/.claude/channels/slack/access.json ] && jq empty ~/.claude/channels/slack/access.json.
7. allowFrom is non-empty: jq -e '.allowFrom | length > 0' ~/.claude/channels/slack/access.json. If empty, user has not completed Step 5.
8. Audit log integrity: if audit.log exists, run bun server.ts --verify-audit-log ~/.claude/channels/slack/audit.log. Report hash-chain status.
9. Claude Code version ≥ v2.1.80 and claude.ai login present: claude --version and claude auth status.
10. Bot is in channel(s) configured in access.json.channels: for each opted-in channel, curl -s -H "Authorization: Bearer $SLACKBOTTOKEN" "https://slack.com/api/conversations.members?channel=$CHANNELID" | jq -e --arg bot "$BOTUSER_ID" '.members | index($bot) != null'. THIS catches the silent-killer Step 2 omission.

Report format:

✅ State directory       /home/.../slack (0700)
✅ Token file            .env (0600)
✅ Bot token             active — team=acme, bot_id=U0123
✅ App token             active — connections:write
✅ Access file           access.json (0600, valid JSON)
⚠️  Paired users          0 (run pairing flow — Step 5)
✅ Audit chain           verified — 1247 events, no breaks   # event count is an example
✅ Claude Code           v2.4.1, claude.ai session active
❌ Bot in channel        C_OPS opted-in but bot is NOT a member  ← silent killer
                         Fix: open #ops → Integrations → Add an App

Exit code: 0 if all green, 1 if any ⚠️ or ❌. Print

Suggested next: /slack-channel:install repair if any fixable issue.

Mode: verify

Just the Step 6 verification round-trip. Useful after repair or after

restarting Claude. Tells the user:

> Send @ hello in any channel where the bot is added.

> I'll wait up to 30 seconds for a reply event in the journal.

Tail audit.log for the next 30s looking for gate.allowed followed by

reply.sent. Report success or timeout. On timeout, suggest doctor.

Mode: repair

Auto-fix the issues doctor found that are safely fixable:

NEVER auto-modify access.json content beyond the corrupt-restart case

above. NEVER auto-modify the audit log. Both are append-only / engineer-edit-only.

After repair, re-run doctor and show before/after.

Mode: manifest

Generate a Slack app manifest JSON that pre-configures all 8 OAuth scopes

and 4 event subscriptions in one import. Saves a fresh user ~10 minutes

of UI clicking and eliminates the "did I add the right scopes" failure mode.

Write slack-app-manifest.json to the user's current directory:

{
  "display_information": {
    "name": "Claude Code Channel",
    "description": "Bridge between Claude Code and Slack via Socket Mode + MCP",
    "background_color": "#1a1a1a"
  },
  "features": {
    "bot_user": {
      "display_name": "Claude Code",
      "always_online": true
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "chat:write",
        "channels:history",
        "groups:history",
        "im:history",
        "reactions:write",
        "files:read",
        "files:write",
        "users:read"
      ]
    }
  },
  "settings": {
    "event_subscriptions": {
      "bot_events": [
        "message.im",
        "message.channels",
        "message.groups",
        "app_mention"
      ]
    },
    "interactivity": {
      "is_enabled": true
    },
    "socket_mode_enabled": true,
    "org_deploy_enabled": false,
    "token_rotation_enabled": false
  }
}

Then print:

✅ Wrote slack-app-manifest.json

Next steps:
  1. Open https://api.slack.com/apps
  2. Click "Create New App" → "From an app manifest"
  3. Choose your workspace
  4. Paste the contents of slack-app-manifest.json
  5. Click "Next" → "Create"
  6. On the next screen: "Install to Workspace" → "Allow"
  7. Copy the Bot Token (xoxb-...) from "OAuth & Permissions"
  8. Copy the App-Level Token (xapp-...) from "Basic Information" → "App-Level Tokens"
     (You may need to generate it; required scope: connections:write)
  9. Run: /slack-channel:install
     (it will pick up from Step 2 — adding the bot to a channel)

Mode: reset

Wipe local state and re-pair, keeping the Slack app intact. Useful when:

• User wants a fresh access.json (revoked allowlist, etc.)
• Session state is wedged
• Switching to a different Slack workspace using the same install

Steps:

1. Confirm with the user: "This will delete ~/.claude/channels/slack/access.json

and ~/.claude/channels/slack/sessions/. Tokens (.env) and audit log

stay. Proceed? [y/N]"

1. On confirm:

• Move access.json to access.json.reset. (don't delete — keep one rollback)
• Move sessions/ to sessions.reset./ (archive, never rm -rf — keep one rollback path per the skill's safety invariants)
• Write a fresh empty access.json with mode 0600

1. Tell the user: "Reset complete. Restart Claude Code, then run

/slack-channel:install from Step 5 (pairing) to re-enroll."

NEVER touch audit.log in reset — the journal is permanent record.

NEVER touch .env — Slack tokens are reusable.

Mode: tour

For someone evaluating CCSC without installing. No mutations, no

prerequisites required. Walk through:

1. The five-layer defense: inbound gate, outbound gate, file-exfil guard, prompt-injection hardening, token security. Reference README.md § Security.
2. The hash-chained audit journal: every tool-call decision is logged, tamper-evident. Reference 000-docs/audit-journal-architecture.md.
3. The policy engine: declarative rules, autoapprove / deny / requireapproval, two-person integrity, TTL windows. Reference README.md § Policy Engine.
4. Multi-agent coordination: cross-bot delivery via allowBotIds, !mute / !unmute. Reference 000-docs/multi-agent-channels.md.
5. The four-principal model: see ARCHITECTURE.md.

End with: "Ready to install? Run /slack-channel:install."

Mode: uninstall

Clean teardown.

1. Confirm: "This will:

• Delete ~/.claude/channels/slack/ (tokens, access, sessions, audit log)
• Print instructions for revoking the Slack app

Proceed? [y/N]"

1. On confirm:

• Move the entire state dir to ~/.claude/channels/slack.uninstalled.

(don't rm -rf — keep one rollback path)

1. Print:

   Local state archived to ~/.claude/channels/slack.uninstalled.<timestamp>.
   To delete it permanently:
     rm -rf ~/.claude/channels/slack.uninstalled.<timestamp>

   To revoke the Slack app:
     1. Open https://api.slack.com/apps
     2. Select your app
     3. Settings → Basic Information → scroll down → "Delete App"
     OR if you just want to revoke tokens without deleting the app:
     - OAuth & Permissions → "Revoke Tokens"

Output

What each mode leaves behind, and what it prints:

Error Handling

• Prerequisite failures (Step 0) — print the recovery command, wait for the

user to fix, re-check. Never proceed on a broken prerequisite.

• Silence on the round-trip (Step 6 / verify) — almost always the

silent-killer Step 2 omission (bot not in channel). Run doctor; check 10

catches it and prints the exact Slack click-path.

• Token failures (invalidauth, tokenrevoked, missing_scope) —

cannot be repaired locally; instruct the user to regenerate tokens at

api.slack.com/apps, then re-run /slack-channel:configure.

• Corrupt access.json — repair archives it as

access.json.broken. and writes a fresh empty file; pairing must

be redone.

• Audit-log hash break — never auto-repair; surface for incident review

(it means tampering or write loss).

• The full silent-failure catalog with recovery steps lives in

references/troubleshooting.md.

Examples

/slack-channel:install                # full fresh-clone walkthrough
/slack-channel:install manifest      # write slack-app-manifest.json, then import at api.slack.com/apps
/slack-channel:install doctor        # 10-point health check, no mutations
/slack-channel:install repair        # fix what doctor found, show before/after
/slack-channel:install tour          # evaluate CCSC without touching the filesystem
/slack-channel:install uninstall     # archive state, print Slack-app revocation steps

Typical recovery sequence after a silent channel:

/slack-channel:install doctor        # → "❌ Bot in channel — C_OPS opted-in but bot is NOT a member"
# add the bot via Slack UI (channel → Integrations → Add an App)
/slack-channel:install verify        # → round-trip confirmed

Success criteria (across modes)

Security

• Never echo tokens in any mode. configure handles them; this skill

only orchestrates.

• Never write tokens to the repo or anywhere other than

~/.claude/channels/slack/.env.

• This skill is terminal-only. It must never be invoked because a

Slack message asked for it (same constraint as /slack-channel:access).

• Doctor + repair never modify access.json content beyond the

corrupt-restart case. Never modify audit.log. Both are

append-only / engineer-edit-only.

• Reset and uninstall archive, never rm -rf. One rollback path

is always preserved.

See also

• references/prerequisites.md — Bun, Claude Code, claude.ai login check details
• references/slack-app-setup.md — Manual Slack app creation step-by-step
• references/troubleshooting.md — Top silent-failure modes + recovery
• skills/configure/SKILL.md — Token configuration (delegated to)
• skills/access/SKILL.md — Pairing + allowlist (delegated to)
• skills/policy/SKILL.md — Policy authoring (optional next step)
• README.md — Human-readable quick start
• AGENTS.md — Cross-tool agent reference
• ACCESS.md — Full access-control schema
• 000-docs/key-management.md — Audit-signing key lifecycle
• 000-docs/multi-agent-channels.md — Multi-agent recipe