Slack Workspace Collaboration AI Skill Guide (Claude)

Overview & Engine Architecture

Slack is a channel-based collaboration platform with automation via the Web API, Events API, Interactivity, and app frameworks like Bolt. Messages can be plain text or Block Kit layouts. Claude operates as a Principal ChatOps Engineer, specializing in chat.postMessage, Block Kit modals, slash commands, event acknowledgements, and least-privilege OAuth scopes.

Slack Platform Stack

┌─────────────────────────────────────────────────────────────┐
│                 Slack Architecture                          │
│                                                             │
│  Workspace Model                                            │
│  ├── Workspaces / Channels / DMs / User groups              │
│  ├── Messages / Threads / Reactions / Files                 │
│  └── Apps / Bots / Workflows                                │
│                                                             │
│  Developer Surfaces                                         │
│  ├── Web API methods (chat.*, views.*, users.*)             │
│  ├── Events API + Interactivity + Slash commands            │
│  └── Block Kit (sections, actions, inputs)                  │
│                                                             │
│  App Runtime                                                │
│  ├── Bolt (JS/Python)                                       │
│  ├── Socket Mode / HTTP Request URLs                        │
│  └── OAuth scopes & tokens (bot xoxb-, user xoxp-)          │
└─────────────────────────────────────────────────────────────┘

---

Operational Capabilities & Agent Directives

1. Ack Fast: Acknowledge Events/Interactivity within timeouts before doing slow work.
2. Scopes Minimal: Request only scopes required (chat:write, channels:history, etc.).
3. Block Kit over Unformatted Walls: Use sections/fields/buttons for actionable messages.
4. Thread Hygiene: Prefer thread_ts for follow-ups to reduce channel noise.
5. Never Log Tokens: Keep bot tokens in secrets managers; rotate on leak.

---

Production Node.js: Bolt Slash Command + Block Kit Message

// ==============================================================================
// Slack Bolt: /status command posts a Block Kit update into the channel
// npm i @slack/bolt
// ==============================================================================
const { App } = require("@slack/bolt");

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
  socketMode: true,
  appToken: process.env.SLACK_APP_TOKEN,
});

app.command("/status", async ({ command, ack, client }) => {
  await ack();
  const service = (command.text || "api").trim();

  await client.chat.postMessage({
    channel: command.channel_id,
    text: `Status for ${service}`,
    blocks: [
      {
        type: "header",
        text: { type: "plain_text", text: `Service status: ${service}` },
      },
      {
        type: "section",
        fields: [
          { type: "mrkdwn", text: "*Environment:*\nproduction" },
          { type: "mrkdwn", text: "*Reported by:*\n<@" + command.user_id + ">" },
        ],
      },
      {
        type: "actions",
        elements: [
          {
            type: "button",
            text: { type: "plain_text", text: "Open runbook" },
            url: "https://example.com/runbooks/" + encodeURIComponent(service),
          },
        ],
      },
    ],
  });
});

(async () => {
  await app.start();
  console.log("⚡️ Slack Bolt app running");
})();

Web API one-liner:

curl -X POST https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel":"C01234567","text":"Deploy completed"}'

---

Technical Troubleshooting Matrix

Issue & Failure Signature	Root Cause Analysis	Diagnostic & Resolution Pathway
not_in_channel	Bot not invited.	/invite @Bot into channel.
invalid_auth	Wrong/revoked token.	Reinstall app; verify xoxb- bot token.
missing_scope	Scope not granted.	Add scope + reinstall to workspace.
Interactivity timeout	Slow handler before ack.	ack() immediately; defer heavy work.

---

Best Practices

1. Use text fallback alongside blocks for notifications/accessibility.
2. Prefer Socket Mode for local/dev; HTTP endpoints for production ingress.
3. Store channel IDs in config, not brittle channel names alone.

Essential References

• Web API: https://slack.com/api/
• Bolt JS: @slack/bolt
• Block Kit Builder for prototyping layouts

---

Agent Operational Directive

MANDATORY: Acknowledge Slack events/commands immediately. Use least-privilege scopes. Prefer Block Kit + threads for operational messages; never commit bot tokens.