block-kit

Block Kit

Help the developer build a rich Block Kit layout. If $0 is provided, it specifies the target surface (message, modal, or home-tab).

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.