Vibeship-spawner-skills slack-bot-builder

Slack Bot Builder Skill

install

source · Clone the upstream repo

git clone https://github.com/vibeforge1111/vibeship-spawner-skills

manifest: integrations/slack-bot-builder/skill.yaml

Slack Bot Builder Skill

Building Slack apps with Bolt framework, Block Kit, and workflows

id: slack-bot-builder name: Slack Bot Builder category: integrations description: | Build Slack apps using the Bolt framework across Python, JavaScript, and Java. Covers Block Kit for rich UIs, interactive components, slash commands, event handling, OAuth installation flows, and Workflow Builder integration. Focus on best practices for production-ready Slack apps.

version: 1.0.0

triggers:

"slack bot"
"slack app"
"bolt framework"
"block kit"
"slash command"
"slack webhook"
"slack workflow"
"slack interactive"
"slack oauth"

============================================================================

CORE PATTERNS

============================================================================

patterns:

id: bolt-app-pattern name: Bolt App Foundation Pattern description: | The Bolt framework is Slack's recommended approach for building apps. It handles authentication, event routing, request verification, and HTTP request processing so you can focus on app logic.

Key benefits:

Event handling in a few lines of code
Security checks and payload validation built-in
Organized, consistent patterns
Works for experiments and production

Available in: Python, JavaScript (Node.js), Java when_to_use:

"Starting any new Slack app"
"Migrating from legacy Slack APIs"
"Building production Slack integrations" implementation: |

Python Bolt App

from slack_bolt import App from slack_bolt.adapter.socket_mode import SocketModeHandler import os

Initialize with tokens from environment

app = App( token=os.environ["SLACK_BOT_TOKEN"], signing_secret=os.environ["SLACK_SIGNING_SECRET"] )

Handle messages containing "hello"

@app.message("hello") def handle_hello(message, say): """Respond to messages containing 'hello'.""" user = message["user"] say(f"Hey there <@{user}>!")

Handle slash command

@app.command("/ticket") def handle_ticket_command(ack, body, client): """Handle /ticket slash command.""" # Acknowledge immediately (within 3 seconds) ack()

  # Open a modal for ticket creation
  client.views_open(
      trigger_id=body["trigger_id"],
      view={
          "type": "modal",
          "callback_id": "ticket_modal",
          "title": {"type": "plain_text", "text": "Create Ticket"},
          "submit": {"type": "plain_text", "text": "Submit"},
          "blocks": [
              {
                  "type": "input",
                  "block_id": "title_block",
                  "element": {
                      "type": "plain_text_input",
                      "action_id": "title_input"
                  },
                  "label": {"type": "plain_text", "text": "Title"}
              },
              {
                  "type": "input",
                  "block_id": "desc_block",
                  "element": {
                      "type": "plain_text_input",
                      "multiline": True,
                      "action_id": "desc_input"
                  },
                  "label": {"type": "plain_text", "text": "Description"}
              },
              {
                  "type": "input",
                  "block_id": "priority_block",
                  "element": {
                      "type": "static_select",
                      "action_id": "priority_select",
                      "options": [
                          {"text": {"type": "plain_text", "text": "Low"}, "value": "low"},
                          {"text": {"type": "plain_text", "text": "Medium"}, "value": "medium"},
                          {"text": {"type": "plain_text", "text": "High"}, "value": "high"}
                      ]
                  },
                  "label": {"type": "plain_text", "text": "Priority"}
              }
          ]
      }
  )

Handle modal submission

@app.view("ticket_modal") def handle_ticket_submission(ack, body, client, view): """Handle ticket modal submission.""" ack()

  # Extract values from the view
  values = view["state"]["values"]
  title = values["title_block"]["title_input"]["value"]
  desc = values["desc_block"]["desc_input"]["value"]
  priority = values["priority_block"]["priority_select"]["selected_option"]["value"]
  user_id = body["user"]["id"]

  # Create ticket in your system
  ticket_id = create_ticket(title, desc, priority, user_id)

  # Notify user
  client.chat_postMessage(
      channel=user_id,
      text=f"Ticket #{ticket_id} created: {title}"
  )

Handle button clicks

@app.action("approve_button") def handle_approval(ack, body, client): """Handle approval button click.""" ack()

  # Get context from the action
  user = body["user"]["id"]
  action_value = body["actions"][0]["value"]

  # Update the message to remove interactive elements
  # (Best practice: prevent double-clicks)
  client.chat_update(
      channel=body["channel"]["id"],
      ts=body["message"]["ts"],
      text=f"Approved by <@{user}>",
      blocks=[]  # Remove interactive blocks
  )

Listen for app_home_opened events

@app.event("app_home_opened") def update_home_tab(client, event): """Update the Home tab when user opens it.""" client.views_publish( user_id=event["user"], view={ "type": "home", "blocks": [ { "type": "section", "text": { "type": "mrkdwn", "text": "Welcome to the Ticket Bot!" } }, { "type": "actions", "elements": [ { "type": "button", "text": {"type": "plain_text", "text": "Create Ticket"}, "action_id": "create_ticket_button" } ] } ] } )

Socket Mode for development (no public URL needed)

if name == "main": handler = SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]) handler.start()

For production, use HTTP mode with a web server

from flask import Flask, request

from slack_bolt.adapter.flask import SlackRequestHandler

flask_app = Flask(name)

handler = SlackRequestHandler(app)

@flask_app.route("/slack/events", methods=["POST"])

def slack_events():

return handler.handle(request)

anti_patterns:

"Not acknowledging requests within 3 seconds"
"Blocking operations in the ack handler"
"Hardcoding tokens in source code"
"Not using Socket Mode for development"

id: block-kit-pattern name: Block Kit UI Pattern description: | Block Kit is Slack's UI framework for building rich, interactive messages. Compose messages using blocks (sections, actions, inputs) and elements (buttons, menus, text inputs).

Limits:

Up to 50 blocks per message
Up to 100 blocks in modals/Home tabs
Block text limited to 3000 characters

Use Block Kit Builder to prototype: https://app.slack.com/block-kit-builder when_to_use:

"Building rich message layouts"
"Adding interactive components to messages"
"Creating forms in modals"
"Building Home tab experiences" implementation: | from slack_bolt import App import os

app = App(token=os.environ["SLACK_BOT_TOKEN"])

def build_notification_blocks(incident: dict) -> list: """Build Block Kit blocks for incident notification.""" severity_emoji = { "critical": ":red_circle:", "high": ":large_orange_circle:", "medium": ":large_yellow_circle:", "low": ":white_circle:" }

  return [
      # Header
      {
          "type": "header",
          "text": {
              "type": "plain_text",
              "text": f"{severity_emoji.get(incident['severity'], '')} Incident Alert"
          }
      },
      # Details section
      {
          "type": "section",
          "fields": [
              {
                  "type": "mrkdwn",
                  "text": f"*Incident:*\n{incident['title']}"
              },
              {
                  "type": "mrkdwn",
                  "text": f"*Severity:*\n{incident['severity'].upper()}"
              },
              {
                  "type": "mrkdwn",
                  "text": f"*Service:*\n{incident['service']}"
              },
              {
                  "type": "mrkdwn",
                  "text": f"*Reported:*\n<!date^{incident['timestamp']}^{date_short} {time}|{incident['timestamp']}>"
              }
          ]
      },
      # Description
      {
          "type": "section",
          "text": {
              "type": "mrkdwn",
              "text": f"*Description:*\n{incident['description'][:2000]}"
          }
      },
      # Divider
      {"type": "divider"},
      # Action buttons
      {
          "type": "actions",
          "block_id": f"incident_actions_{incident['id']}",
          "elements": [
              {
                  "type": "button",
                  "text": {"type": "plain_text", "text": "Acknowledge"},
                  "style": "primary",
                  "action_id": "acknowledge_incident",
                  "value": incident['id']
              },
              {
                  "type": "button",
                  "text": {"type": "plain_text", "text": "Resolve"},
                  "style": "danger",
                  "action_id": "resolve_incident",
                  "value": incident['id'],
                  "confirm": {
                      "title": {"type": "plain_text", "text": "Resolve Incident?"},
                      "text": {"type": "mrkdwn", "text": "Are you sure this incident is resolved?"},
                      "confirm": {"type": "plain_text", "text": "Yes, Resolve"},
                      "deny": {"type": "plain_text", "text": "Cancel"}
                  }
              },
              {
                  "type": "button",
                  "text": {"type": "plain_text", "text": "View Details"},
                  "action_id": "view_incident",
                  "value": incident['id'],
                  "url": f"https://incidents.example.com/{incident['id']}"
              }
          ]
      },
      # Context footer
      {
          "type": "context",
          "elements": [
              {
                  "type": "mrkdwn",
                  "text": f"Incident ID: {incident['id']} | <https://runbook.example.com/{incident['service']}|View Runbook>"
              }
          ]
      }
  ]

def send_incident_notification(channel: str, incident: dict): """Send incident notification with Block Kit.""" blocks = build_notification_blocks(incident)

  app.client.chat_postMessage(
      channel=channel,
      text=f"Incident: {incident['title']}",  # Fallback for notifications
      blocks=blocks
  )

Handle button actions

@app.action("acknowledge_incident") def handle_acknowledge(ack, body, client): """Handle incident acknowledgment.""" ack()

  incident_id = body["actions"][0]["value"]
  user = body["user"]["id"]

  # Update your system
  acknowledge_incident(incident_id, user)

  # Update message to show acknowledgment
  original_blocks = body["message"]["blocks"]

  # Add acknowledgment to context
  original_blocks[-1]["elements"].append({
      "type": "mrkdwn",
      "text": f":white_check_mark: Acknowledged by <@{user}>"
  })

  # Remove acknowledge button (prevent double-click)
  action_block = next(b for b in original_blocks if b.get("block_id", "").startswith("incident_actions"))
  action_block["elements"] = [e for e in action_block["elements"] if e["action_id"] != "acknowledge_incident"]

  client.chat_update(
      channel=body["channel"]["id"],
      ts=body["message"]["ts"],
      blocks=original_blocks
  )

Interactive select menus

def build_user_selector_blocks(): """Build blocks with user selector.""" return [ { "type": "section", "text": {"type": "mrkdwn", "text": "Assign this task:"}, "accessory": { "type": "users_select", "action_id": "assign_user", "placeholder": {"type": "plain_text", "text": "Select assignee"} } } ]

Overflow menu for more options

def build_task_blocks(task: dict): """Build task blocks with overflow menu.""" return [ { "type": "section", "text": {"type": "mrkdwn", "text": f"{task['title']}"}, "accessory": { "type": "overflow", "action_id": "task_overflow", "options": [ { "text": {"type": "plain_text", "text": "Edit"}, "value": f"edit_{task['id']}" }, { "text": {"type": "plain_text", "text": "Delete"}, "value": f"delete_{task['id']}" }, { "text": {"type": "plain_text", "text": "Share"}, "value": f"share_{task['id']}" } ] } } ] anti_patterns:

"Exceeding 50 blocks per message"
"Not providing fallback text for accessibility"
"Hardcoding action_ids (use dynamic IDs when needed)"
"Not handling button clicks idempotently"

id: oauth-installation-pattern name: OAuth Installation Pattern description: | Enable users to install your app in their workspaces via OAuth 2.0. Bolt handles most of the OAuth flow, but you need to configure it and store tokens securely.

Key OAuth concepts:

Scopes define permissions (request minimum needed)
Tokens are workspace-specific
Installation data must be stored persistently
Users can add scopes later (additive)

70% of users abandon installation when confronted with excessive permission requests - request only what you need! when_to_use:

"Distributing app to multiple workspaces"
"Building public Slack apps"
"Enterprise-grade integrations" implementation: | from slack_bolt import App from slack_bolt.oauth.oauth_settings import OAuthSettings from slack_sdk.oauth.installation_store import FileInstallationStore from slack_sdk.oauth.state_store import FileOAuthStateStore import os

For production, use database-backed stores

For example: PostgreSQL, MongoDB, Redis

class DatabaseInstallationStore: """Store installation data in your database."""

  async def save(self, installation):
      """Save installation when user completes OAuth."""
      await db.installations.upsert({
          "team_id": installation.team_id,
          "enterprise_id": installation.enterprise_id,
          "bot_token": encrypt(installation.bot_token),
          "bot_user_id": installation.bot_user_id,
          "bot_scopes": installation.bot_scopes,
          "user_id": installation.user_id,
          "installed_at": installation.installed_at
      })

  async def find_installation(self, *, enterprise_id, team_id, user_id=None, is_enterprise_install=False):
      """Find installation for a workspace."""
      record = await db.installations.find_one({
          "team_id": team_id,
          "enterprise_id": enterprise_id
      })

      if record:
          return Installation(
              bot_token=decrypt(record["bot_token"]),
              # ... other fields
          )
      return None

Initialize OAuth-enabled app

app = App( signing_secret=os.environ["SLACK_SIGNING_SECRET"], oauth_settings=OAuthSettings( client_id=os.environ["SLACK_CLIENT_ID"], client_secret=os.environ["SLACK_CLIENT_SECRET"], scopes=[ "channels:history", "channels:read", "chat:write", "commands", "users:read" ], user_scopes=[], # User token scopes if needed installation_store=DatabaseInstallationStore(), state_store=FileOAuthStateStore(expiration_seconds=600) ) )

OAuth routes are handled automatically by Bolt

/slack/install - Initiates OAuth flow

/slack/oauth_redirect - Handles callback

Flask integration

from flask import Flask, request from slack_bolt.adapter.flask import SlackRequestHandler

flask_app = Flask(name) handler = SlackRequestHandler(app)

@flask_app.route("/slack/install", methods=["GET"]) def install(): return handler.handle(request)

@flask_app.route("/slack/oauth_redirect", methods=["GET"]) def oauth_redirect(): return handler.handle(request)

@flask_app.route("/slack/events", methods=["POST"]) def slack_events(): return handler.handle(request)

Handle installation success/failure

@app.oauth_success def handle_oauth_success(args): """Called when OAuth completes successfully.""" installation = args["installation"]

  # Send welcome message
  app.client.chat_postMessage(
      token=installation.bot_token,
      channel=installation.user_id,
      text="Thanks for installing! Type /help to get started."
  )

  return "Installation successful! You can close this window."

@app.oauth_failure def handle_oauth_failure(args): """Called when OAuth fails.""" error = args.get("error", "Unknown error") return f"Installation failed: {error}"

Scope management - request additional scopes when needed

def request_additional_scopes(team_id: str, new_scopes: list): """ Generate URL for user to add scopes. Note: Existing tokens retain old scopes. User must re-authorize for new scopes. """ base_url = "https://slack.com/oauth/v2/authorize" params = { "client_id": os.environ["SLACK_CLIENT_ID"], "scope": ",".join(new_scopes), "team": team_id } return f"{base_url}?{urlencode(params)}" anti_patterns:

"Requesting unnecessary scopes upfront"
"Storing tokens in plain text"
"Not validating OAuth state parameter (CSRF risk)"
"Assuming tokens have new scopes after config change"

id: socket-mode-pattern name: Socket Mode Pattern description: | Socket Mode allows your app to receive events via WebSocket instead of public HTTP endpoints. Perfect for development and apps behind firewalls.

Benefits:
- No public URL needed
- Works behind corporate firewalls
- Simpler local development
- Real-time bidirectional communication
Limitation: Not recommended for high-volume production apps. when_to_use:
- "Local development"
- "Apps behind corporate firewalls"
- "Internal tools with security constraints"
- "Prototyping and testing" implementation: | from slack_bolt import App from slack_bolt.adapter.socket_mode import SocketModeHandler import os
Socket Mode requires an app-level token (xapp-...)

Create in App Settings > Basic Information > App-Level Tokens

Needs 'connections:write' scope

app = App(token=os.environ["SLACK_BOT_TOKEN"])

@app.message("hello") def handle_hello(message, say): say(f"Hey <@{message['user']}>!")

@app.command("/status") def handle_status(ack, say): ack() say("All systems operational!")

@app.event("app_mention") def handle_mention(event, say): say(f"You mentioned me, <@{event['user']}>!")

if name == "main": # SocketModeHandler manages the WebSocket connection handler = SocketModeHandler( app, os.environ["SLACK_APP_TOKEN"] # xapp-... token )
```
  print("Starting Socket Mode...")
  handler.start()
```
For async apps

from slack_bolt.async_app import AsyncApp from slack_bolt.adapter.socket_mode.async_handler import AsyncSocketModeHandler import asyncio

async_app = AsyncApp(token=os.environ["SLACK_BOT_TOKEN"])

@async_app.message("hello") async def handle_hello_async(message, say): await say(f"Hey <@{message['user']}>!")

async def main(): handler = AsyncSocketModeHandler(async_app, os.environ["SLACK_APP_TOKEN"]) await handler.start_async()

if name == "main": asyncio.run(main()) anti_patterns:
- "Using Socket Mode for high-volume production apps"
- "Not handling WebSocket disconnections"
- "Forgetting to create app-level token"
- "Using bot token instead of app token"

id: workflow-step-pattern name: Workflow Builder Step Pattern description: | Extend Slack's Workflow Builder with custom steps powered by your app. Users can include your custom steps in their no-code workflows.

Workflow steps can:

Collect input from users
Execute custom logic
Output data for subsequent steps when_to_use:
"Integrating with Workflow Builder"
"Enabling non-technical users to use your features"
"Building reusable automation components" implementation: | from slack_bolt import App from slack_bolt.workflows.step import WorkflowStep import os

app = App( token=os.environ["SLACK_BOT_TOKEN"], signing_secret=os.environ["SLACK_SIGNING_SECRET"] )

Define the workflow step

def edit(ack, step, configure): """Called when user adds/edits the step in Workflow Builder.""" ack()

  # Show configuration modal
  blocks = [
      {
          "type": "input",
          "block_id": "ticket_type",
          "element": {
              "type": "static_select",
              "action_id": "type_select",
              "options": [
                  {"text": {"type": "plain_text", "text": "Bug"}, "value": "bug"},
                  {"text": {"type": "plain_text", "text": "Feature"}, "value": "feature"},
                  {"text": {"type": "plain_text", "text": "Task"}, "value": "task"}
              ]
          },
          "label": {"type": "plain_text", "text": "Ticket Type"}
      },
      {
          "type": "input",
          "block_id": "title_input",
          "element": {
              "type": "plain_text_input",
              "action_id": "title"
          },
          "label": {"type": "plain_text", "text": "Title"}
      },
      {
          "type": "input",
          "block_id": "assignee_input",
          "element": {
              "type": "users_select",
              "action_id": "assignee"
          },
          "label": {"type": "plain_text", "text": "Assignee"}
      }
  ]

  configure(blocks=blocks)

def save(ack, view, update): """Called when user saves step configuration.""" ack()

  values = view["state"]["values"]

  # Define inputs (from user's configuration)
  inputs = {
      "ticket_type": {
          "value": values["ticket_type"]["type_select"]["selected_option"]["value"]
      },
      "title": {
          "value": values["title_input"]["title"]["value"]
      },
      "assignee": {
          "value": values["assignee_input"]["assignee"]["selected_user"]
      }
  }

  # Define outputs (available to subsequent steps)
  outputs = [
      {
          "name": "ticket_id",
          "type": "text",
          "label": "Created Ticket ID"
      },
      {
          "name": "ticket_url",
          "type": "text",
          "label": "Ticket URL"
      }
  ]

  update(inputs=inputs, outputs=outputs)

def execute(step, complete, fail): """Called when the step runs in a workflow.""" inputs = step["inputs"]

  try:
      # Get input values
      ticket_type = inputs["ticket_type"]["value"]
      title = inputs["title"]["value"]
      assignee = inputs["assignee"]["value"]

      # Create ticket in your system
      ticket = create_ticket(
          type=ticket_type,
          title=title,
          assignee=assignee
      )

      # Complete with outputs
      complete(outputs={
          "ticket_id": ticket["id"],
          "ticket_url": ticket["url"]
      })

  except Exception as e:
      fail(error={"message": str(e)})

Register the workflow step

create_ticket_step = WorkflowStep( callback_id="create_ticket_step", edit=edit, save=save, execute=execute )

app.step(create_ticket_step) anti_patterns:

"Not calling complete() or fail() in execute"
"Long-running operations without progress updates"
"Not validating inputs in execute"
"Exposing sensitive data in outputs"

============================================================================

DECISION FRAMEWORK

============================================================================

decision_framework: connection_mode: question: "Socket Mode or HTTP Mode?" options: socket_mode: when: "Development, behind firewall, low volume" pros: "No public URL, simpler setup" cons: "Not for high volume, requires app token"

  http_mode:
    when: "Production, high volume, public app"
    pros: "Scalable, standard HTTP"
    cons: "Needs public URL, more infrastructure"

language_choice: question: "Which Bolt SDK?" options: bolt_python: when: "Python backend, data processing, AI/ML" considerations: "Use async for high concurrency"

  bolt_js:
    when: "Node.js backend, frontend team, serverless"
    considerations: "TypeScript recommended"

  bolt_java:
    when: "Enterprise Java environment"
    considerations: "Less common, good for existing Java"

============================================================================

HANDOFFS

============================================================================

handoffs:

to: twilio-communications when: "Need SMS/voice alongside Slack" context: "Multi-channel notifications"
to: workflow-automation when: "Complex automation beyond Slack" context: "n8n/Temporal for broader workflows"
to: backend when: "Building Slack app backend" context: "API design, database, authentication"
to: devops when: "Deploying Slack app to production" context: "Infrastructure, scaling, monitoring"

============================================================================

QUICK REFERENCE

============================================================================

quick_reference: environment_variables: required: - "SLACK_BOT_TOKEN (xoxb-...)" - "SLACK_SIGNING_SECRET" oauth: - "SLACK_CLIENT_ID" - "SLACK_CLIENT_SECRET" socket_mode: - "SLACK_APP_TOKEN (xapp-...)"

common_scopes: messages: "chat:write, chat:write.public" channels: "channels:read, channels:history" users: "users:read, users:read.email" commands: "commands" files: "files:read, files:write" reactions: "reactions:read, reactions:write"

block_limits: message: 50 modal: 100 home_tab: 100 text_field: 3000

response_times: acknowledge: "3 seconds max" modal_open: "3 seconds max" webhook_response: "3 seconds max"

Vibeship-spawner-skills slack-bot-builder

Slack Bot Builder Skill

Building Slack apps with Bolt framework, Block Kit, and workflows

============================================================================

CORE PATTERNS

============================================================================

Python Bolt App

Initialize with tokens from environment

Handle messages containing "hello"

Handle slash command

Handle modal submission

Handle button clicks

Listen for app_home_opened events

Socket Mode for development (no public URL needed)

For production, use HTTP mode with a web server

from flask import Flask, request

from slack_bolt.adapter.flask import SlackRequestHandler

flask_app = Flask(name)

handler = SlackRequestHandler(app)

@flask_app.route("/slack/events", methods=["POST"])

def slack_events():

return handler.handle(request)

Handle button actions

Interactive select menus

Overflow menu for more options

For production, use database-backed stores

For example: PostgreSQL, MongoDB, Redis

Initialize OAuth-enabled app

OAuth routes are handled automatically by Bolt

/slack/install - Initiates OAuth flow

/slack/oauth_redirect - Handles callback

Flask integration

Handle installation success/failure

Scope management - request additional scopes when needed

Socket Mode requires an app-level token (xapp-...)

Create in App Settings > Basic Information > App-Level Tokens

Needs 'connections:write' scope

For async apps

Define the workflow step

Register the workflow step

============================================================================

DECISION FRAMEWORK

============================================================================

============================================================================

HANDOFFS

============================================================================

============================================================================

QUICK REFERENCE

============================================================================