slackapi/slack-mcp-plugin/block-kit

Block Kit

Help the developer build a rich Block Kit layout. If $0 is exactly message, modal, or home-tab, treat it as the target surface. Otherwise (including if it's empty or any other value), ignore it and determine the surface in Step 1.

This skill walks through surface selection, layout planning, JSON generation, and validation. Block types, elements, and fields come from the live docs (see Source of Truth below) — discover them and read each component's schema there, never from memory.

Common Block Kit mistakes (and why): A few errors recur often enough to flag up front. Most others are caught by blocks.validate in Step 5, so lean on validation rather than memorizing rules.

- `"type": "text"` is not a thing. Text is a composition object: { "type": "plain_text", "text": "..." } or { "type": "mrkdwn", "text": "..." }.

- `markdown` is a _block_ type, not a text type. A markdown block holds standard markdown; text objects inside other blocks use mrkdwn (see mrkdwn vs. the `markdown` block in Step 4). Slack's mrkdwn is *bold* / _italic_ / ~strike~, not **bold**.

- Messages need a top-level `text` fallback. blocks.validate won't flag a missing one, but notifications and screen readers display it instead of the blocks — so summarize what the layout conveys rather than leaving it empty.

Source of Truth: the Live Docs

Every block, element, and composition object is documented on docs.slack.dev. Append .md to any reference URL to fetch it as markdown with WebFetch (no auth required).

• Master index: the authoritative list of every block, block element, and composition object, each linking to its own page: https://docs.slack.dev/reference/block-kit.md. WebFetch it to confirm a type exists and to get the link to its page.
• Per-component pages carry the full field schema (a fields table with required/optional flags and constraints, plus JSON examples):
• Blocks: https://docs.slack.dev/reference/block-kit/blocks/<slug>-block.md
• Block elements: https://docs.slack.dev/reference/block-kit/block-elements/<slug>-element.md
• Composition objects: https://docs.slack.dev/reference/block-kit/composition-objects/<slug>.md
• The slug is not always the type name. For example datepicker maps to date-picker-element.md, and every *_select menu (static_select, users_select, multi_channels_select, and so on) is documented on select-menu-element.md. When unsure of a slug, follow the link from the master index rather than building the URL by hand.
• Surface payload structure lives in the surface guides: messages at https://docs.slack.dev/messaging/formatting-message-text.md, modals at https://docs.slack.dev/surfaces/modals.md, and Home tabs at https://docs.slack.dev/surfaces/app-home.md.

Never use a block type, element, or field you have not seen on a live page.

Fast Path (for clear, specific requests)

If the developer's request is specific enough to determine both the target surface and the desired layout, collapse Steps 1-4 into a single pass:

1. Determine the surface from $0 or context
2. Fetch only the doc pages for the blocks and elements mentioned
3. Generate the JSON directly
4. Proceed to Step 5 (validation)

Fast-path indicators (skip the full workflow):

• Developer provides existing JSON to modify → use Modification Mode instead
• Developer names specific block types: "add an actions block with two buttons"
• Developer describes a well-known pattern: "approval message", "feedback form", "settings modal"
• Developer provides a complete description in one message with enough detail to build

Full-workflow indicators (use Steps 1-7):

• Vague requests: "make something cool", "build a dashboard"
• Exploratory: "what can Block Kit do?", "show me my options"
• Complex layouts: 10+ blocks, nested modals, conditional logic
• Developer asks for help deciding what to build

Modification Mode

If the developer provides existing Block Kit JSON (pasted inline, in a file, or referenced from code), enter Modification Mode instead of the full creation workflow:

1. Parse the existing structure:

• List each block by index, type, and a short description of its content
• Infer the surface: "type": "modal" = modal, "type": "home" = home tab, bare blocks array = message

1. Ask what changes they want:

• Add blocks (where in the sequence?)
• Remove blocks (which ones?)
• Modify blocks (which block, what change?)
• Reorder blocks

1. Apply changes while preserving:

• All existing block_id values (these are referenced in app interaction handlers)
• All existing action_id values (these map to event listeners)
• Existing styles, text content, and structure for unchanged blocks

1. Validate the modified JSON: proceed to Step 5 (validation)

Detection: If the developer's message contains a JSON array starting with [{"type": or a view object with "blocks":, enter Modification Mode automatically. If they say "edit", "update", "modify", or "change" in reference to existing blocks, ask them to provide the current JSON.

Step 1: Determine the Target Surface

If $0 is provided and matches one of message, modal, or home-tab, use it directly.

Otherwise, ask the developer using AskUserQuestion:

• Message: Conversational content posted to a channel or DM. Max 50 blocks.
• Modal: A dialog or form opened by a user action. Max 100 blocks.
• Home tab: A persistent, per-user dashboard in the App Home. Max 100 blocks.

Once the surface is determined, use the correct payload structure for it:

• Message: a { "text": "Fallback text", "blocks": [...] } object posted via chat.postMessage (and friends). The text field is the notification/accessibility fallback. For message text formatting (mrkdwn, mentions, dates), see https://docs.slack.dev/messaging/formatting-message-text.md.
• Modal: a view object ({ "type": "modal", "title": ..., "blocks": [...] }). For the full view object structure, lifecycle, and the rule that submit is required when the view contains any input block, see https://docs.slack.dev/surfaces/modals.md.
• Home tab: a view object ({ "type": "home", "blocks": [...] }) published via views.publish. For structure and behavior, see https://docs.slack.dev/surfaces/app-home.md.

Step 2: Understand What to Build

Ask the developer to describe what they want their layout to look like or accomplish.

If they need inspiration, suggest examples — several map directly onto a ready-made template in references/common-patterns.md (named in parentheses), which you can start from in Step 3:

• "A feedback form with a text input and a category selector" (Simple Form Modal)
• "A deploy-failure notification with a description and next-step buttons" (Notification Alert), or "an approval request with Approve/Reject buttons" (Approval Message)
• "A dashboard home tab with a welcome header, key metrics in fields, and quick-action buttons" (Dashboard Home Tab)
• "A settings modal with dropdowns, checkboxes, and a time picker" (Settings Modal with Multiple Input Types)
• "A table of sprint tasks with status and points" (Data Table)
• "A deploy summary with bold text, a link, and a bullet list" (Rich Text Section)
• "A row-level '⋯' menu for edit/duplicate/delete actions" (Row Actions with Overflow Menu)
• "A product card with an image, price, and Add to Cart button" (Card Preview)

Get enough detail to plan the layout before generating any JSON.

Step 3: Plan the Block Layout

Based on the developer's description:

1. Fetch only what you need from the live docs:

• WebFetch the master index (https://docs.slack.dev/reference/block-kit.md) to confirm the block and element types you plan to use exist and to grab links to their pages.
• Consult references/design-principles.md for design appropriateness — which block fits the shape of the content (table vs. stacked sections, card vs. loose blocks), emphasis, reading order, and accessibility. It is guidance on building layouts that read well, not on validity. Depending on the layout, also consult:
• references/modal-design.md for modals and forms: titles and submit labels, input labels and hints, multi-step flows, validation errors, and loading or success states.
• references/home-tab-design.md for Home tabs: what goes at the top, empty and first-run states, keeping the view current, different views per role, and review surfaces for agents.
• references/data-display-design.md for numbers and records: choosing between section fields, table, data_table, and data_visualization charts, and presenting each clearly.
• references/agent-progress-design.md for showing an agent's work with plan and task_card blocks or streamed task updates.
• references/human-in-the-loop.md for approval gates, approving several proposed actions in one message, clarifying choices, and edit-before-send.
• Check references/common-patterns.md if the request matches a common pattern; start from the template instead of building from scratch.
• Defer reading individual component pages until Step 4, when you build each block's fields.

1. Propose a numbered block outline. For example:

```text

1. header: "Weekly Report"
2. section: Summary text with a datepicker accessory
3. divider
4. section: Status fields (Name, Role, Team)
5. actions: "Approve Report" button (primary) and "Reject" button (unstyled)

```

1. Present the outline to the developer and ask for approval or changes before generating JSON.

Surface constraints to check:

• Block count limit: 50 for messages, 100 for modals/home tabs
• Modal-specific: if using input blocks, the modal payload must include a submit field
• Table: only one table block per message
• Charts: at most two data_visualization blocks per message
• Alert: the alert block is available only in modals. In messages, state severity in words in a header or section.
• Surface compatibility (whether a block is valid on the chosen surface) and element compatibility (whether an element is allowed inside a given block) are not always spelled out on a component's doc page. Check references/design-principles.md's surface and limits table for these. `blocks.validate` in Step 5 does not enforce them — it checks block and element shape only, and will return ok: true for a block on the wrong surface or over a count limit. Don't treat a pass there as confirmation of surface or count compliance.

Step 4: Generate the Block Kit JSON

Once the layout is approved, build each block from its live doc page, fetching each page's fields table (required vs optional, constraints) and JSON example with WebFetch. The URL patterns are in Source of Truth above; the one slug to remember is that every *_select menu (static_select, users_select, multi_channels_select, …) lives on select-menu-element.md. Fetch pages as you need them and reuse what you have already fetched — don't re-fetch the same page for every block of the same type. Then build the payload block-by-block and wrap it in the surface structure from Step 1.

Guidelines:

• Use descriptive action_id values (e.g., "approve_report_btn" not "action_1") — they identify the element in your interaction handlers
• Include block_id values where the developer will need them for interaction handling
• For modals, include title, submit, close, and callback_id; for home tabs, the type: "home" wrapper
• Use mrkdwn text for rich formatting, plain_text where required (headers, labels, modal title)