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.