Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(slack): add generic slack formatting skill (#123529)

Matt Puad8a114455e73
diff --git a/.agents/skills/adding-product-alerting/SKILL.md b/.agents/skills/adding-product-alerting/SKILL.md
index 96aa6fcdadb8..be36a59b128c 100644
--- a/.agents/skills/adding-product-alerting/SKILL.md
+++ b/.agents/skills/adding-product-alerting/SKILL.md
@@ -21,6 +21,8 @@ This skill covers two jobs:
1. Add platform alerting to a product by composing the shared lifecycle, destination, delivery, scheduling, email, and frontend primitives.
2. Extend the alerts platform when a reusable capability, option, or advanced behavior belongs in shared infrastructure.
+For Slack message layout, cards, Markdown, and visual checks, use [formatting-slack-messages](../formatting-slack-messages/SKILL.md).
+
## Route first
| Request | Path | Read |
diff --git a/.agents/skills/developing-subscriptions/SKILL.md b/.agents/skills/developing-subscriptions/SKILL.md
index 134712e2997a..1edb671d5d9d 100644
--- a/.agents/skills/developing-subscriptions/SKILL.md
+++ b/.agents/skills/developing-subscriptions/SKILL.md
@@ -18,6 +18,8 @@ Use `adding-product-alerting` when delivery depends on a threshold, anomaly, bre
When investigating a subscription whose insight is missing, or changing insight deletion or restoration, read the [insight deletion and related-resource contract](../../../products/product_analytics/AGENTS.md).
It defines cleanup for subscriptions, alerts, and dashboard tiles, including single and bulk deletion and restore behavior.
+For Slack message layout, cards, Markdown, and visual checks, use [formatting-slack-messages](../formatting-slack-messages/SKILL.md).
+
## 1. Route the request
| Request | Primary path |
diff --git a/.agents/skills/formatting-slack-messages/SKILL.md b/.agents/skills/formatting-slack-messages/SKILL.md
new file mode 100644
index 000000000000..c10c97a30992
--- /dev/null
+++ b/.agents/skills/formatting-slack-messages/SKILL.md
@@ -0,0 +1,152 @@
+---
+name: formatting-slack-messages
+description: >
+ Builds and validates Slack Block Kit messages, modals, and App Home layouts.
+ Use for Slack formatting, block selection, Markdown, cards, tables, charts,
+ metadata, buttons, and menus. Covers live schemas, payload validation,
+ accessibility, and actual Slack rendering. Not for workspace setup.
+---
+
+# Formatting Slack messages
+
+Build a layout that makes the result, its context, and the next action clear.
+This workflow adapts Slack's official Block Kit skill.
+It is self-contained; another installed skill is not required.
+See [sources](references/block-selection.md#sources-and-attribution) for upstream attribution.
+
+## 1. Identify the surface and the change
+
+Infer the surface from the request or existing payload:
+
+- A message has `blocks` or `attachments` and goes to a channel or direct message.
+- A modal has `type: modal` and a view lifecycle.
+- An App Home view has `type: home` and is published for a user.
+
+Inspect the existing payload before changing its layout.
+For modifications, preserve unchanged content, source links, `block_id`, `action_id`, values, and menu choices.
+Ask only when missing information changes the implementation. Do not repeat questions the user already answered.
+For a clear small edit, read the relevant schema, make the edit, and validate it.
+For a broad redesign, establish the content order before building the payload.
+
+## 2. Read live schemas
+
+Use the [Block Kit index](https://docs.slack.dev/reference/block-kit) to find the current component pages.
+Fetch each selected block, element, and composition object's schema and example.
+Append `.md` to Slack documentation URLs when a Markdown response is easier to read.
+Follow index links rather than guessing slugs; select menus share one reference page.
+Reuse pages already read during the task.
+
+Check required fields, allowed nesting, text types, limits, and supported surfaces separately.
+Do not treat this skill's comparison tables as permanent schemas.
+
+Common errors:
+
+- `markdown` is a block type. It is not a text-object type.
+- Text objects use `plain_text` or `mrkdwn`. A `text` element is valid inside the appropriate `rich_text` structure, not as a standalone block.
+- Valid JSON does not establish valid Block Kit.
+- A schema-validation success does not establish surface compatibility or block-count compliance.
+
+## 3. Match the structure to the content
+
+| Content | Starting point |
+| ------------------------------------------------------------- | ---------------------------------------------------------- |
+| One change or important number | A short sentence with its comparison and units |
+| Independent facts about one item | `section.fields` with short labels and values |
+| Several comparable rows | `table` |
+| Rows that need sorting, pagination, filtering, or row actions | `data_table` |
+| A compact entity with a short body and a few buttons | `card` |
+| Optional peer items for browsing | A `carousel` of cards |
+| A related group of blocks | `container` |
+| A real task or investigation step with progress updates | `task_card` or `plan` |
+| A view-wide notice in a modal | `alert` |
+| Existing generated Markdown | `markdown`, if supported and safe for the intended message |
+| Formatted text assembled in code | `rich_text` |
+
+Use [block selection](references/block-selection.md) for limits, table comparisons, and template patterns.
+Keep required findings visible outside carousels, pagination, and collapsed groups.
+Do not add dividers between every block or put a one-line notice in a card without a reason.
+Use a consistent size and hierarchy across comparable messages.
+Keep at most one visually primary action per message or view. Leave equal navigation choices unstyled.
+
+For modals, check the view wrapper, title, callback, close, and submit requirements.
+An input-containing modal needs a submit action. Do not compete with Submit using another primary button.
+For App Home, handle first use, empty results, and view refresh for the current user.
+Use task cards for work with progress updates. Their states describe task progress.
+
+## 4. Establish a clear hierarchy
+
+- Lead with the main result or subject. Link its name to the source when useful.
+- Explain the result in a short sentence before optional detail.
+- Group related metadata and keep units with values.
+- Avoid repeating the same title, link, or value in adjacent blocks unless it answers a different question.
+- Keep required information and actions outside collapsed or paginated detail.
+- Use consistent widths and emphasis for comparable items.
+- State status in words. Do not rely on color or emoji alone.
+- Show only facts the source provides. Do not invent priority, causes, or recommendations.
+
+Use inline code for identifiers, literal values, names, or short phrases when that emphasis helps the reader.
+Keep surrounding text regular. Reserve stronger emphasis for the few items that matter most.
+Follow the user's chosen emphasis style; do not bold every label and value.
+Use descriptive action labels and avoid duplicate navigation controls.
+For a one-time notification, use wording that remains accurate later. A current status needs an update lifecycle.
+
+### Text formats and safe content
+
+- `mrkdwn` uses `*bold*`, `_italic_`, backticks, and `<url|label>` links.
+- A native `markdown` block uses standard Markdown, including `**bold**` and `[label](url)` links.
+- `rich_text` uses typed elements and explicit styles. Use its `code` style for inline-code emphasis.
+
+Do not pass one format into another unchanged.
+Keep dynamic text separate from formatting syntax. Apply the required link policy before adding links.
+Escape dynamic `mrkdwn` values and prevent unintended mentions. Keep literal identifiers separate from formatting.
+Use Unicode emojis or supported emoji elements; check the text object's `emoji` behavior.
+
+### Charts and accessibility
+
+Choose an image block for a supplied chart image. Use a native chart block when its supported features fit the data.
+State the main finding in text and provide useful `alt_text` for images.
+Check labels, units, image size, and readability on narrow screens.
+
+Supply useful notification and screen-reader fallback text.
+Do not clear top-level `text` only to remove duplication; adjust the visible heading and check the result.
+An attachment fallback is not proof of equivalent accessibility or notification behavior.
+Button labels must explain their action without relying on color or an icon.
+
+## 5. Validate the payload
+
+Use [blocks.validate](https://docs.slack.dev/reference/methods/blocks.validate/) with concrete values in place of placeholders.
+Read the live method reference before choosing request parameters.
+Send exactly one of:
+
+- `blocks`: the JSON-encoded block array.
+- `message`: the JSON-encoded complete message, including attachments.
+- `view`: the JSON-encoded modal or App Home view.
+
+The method requires no scopes. Use an available Slack API client or connector.
+If a Slack CLI is available, read its help before using its API or authentication flags.
+Do not hardcode CLI flags from memory.
+
+Inspect `ok` and each validation error's pointer, message, and constraint.
+Fix the offending fields and validate again.
+Check supported surfaces and count limits independently, including nested blocks.
+For example, `alert` is modal-only, and a container accepts at most ten child blocks.
+A validation success is a schema result, not a visual or functional approval.
+
+## 6. Inspect the rendered layout
+
+Use Block Kit Builder to inspect the intended surface with representative sample content.
+If the user authorizes a live message, send the payload to the authorized destination and inspect its rendering.
+
+Check:
+
+- Long text, long names, missing fields, and empty results.
+- Desktop and narrow layouts.
+- Initial expansion, pagination, and content hidden by scrolling.
+- Text hierarchy, links, emojis, and image readability.
+- Notification and screen-reader fallback text.
+- Button labels and placement. Check interaction behavior separately when it is in scope.
+
+Legacy colored attachments can collapse. Check block support before nesting newer components inside them.
+Keep essential content visible in the initial layout.
+Compare layouts with the same content so their differences are clear.
+Distinguish schema validation, visual inspection, and interaction checks when reporting results.
diff --git a/.agents/skills/formatting-slack-messages/references/block-selection.md b/.agents/skills/formatting-slack-messages/references/block-selection.md
new file mode 100644
index 000000000000..82459175d45f
--- /dev/null
+++ b/.agents/skills/formatting-slack-messages/references/block-selection.md
@@ -0,0 +1,86 @@
+# Slack block selection
+
+Sources checked: 2026-10-26. Recheck current limits and supported surfaces before implementation.
+
+## Upstream design reference
+
+Slack maintains the [block-kit skill](https://github.com/slackapi/slack-skills-plugin/blob/main/skills/block-kit/SKILL.md), [design principles](https://github.com/slackapi/slack-skills-plugin/blob/main/skills/block-kit/references/design-principles.md), and [data-display guide](https://github.com/slackapi/slack-skills-plugin/blob/main/skills/block-kit/references/data-display-design.md).
+Use those sources for general block selection. This reference provides a component comparison, not a replacement schema.
+
+Validate resolved payloads with [blocks.validate](https://docs.slack.dev/reference/methods/blocks.validate/).
+A successful validation does not establish surface support, count limits, initial expansion, or action behavior.
+
+## Blocks and their purpose
+
+| Block | Good fit | Constraints and checks |
+| ---------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `card` | Compact linked result, short summary, navigation buttons | Title and subtitle: 150 characters each. Body and subtext: 200 each. Maximum three action buttons. Keep long summaries and menus outside. |
+| `container` | Summary or report group with a heading and several child blocks | Maximum ten child blocks. Width supports `full`. Use `is_collapsible: false` for essential content. Do not nest it in legacy attachments without a real API check. |
+| `section.fields` | Related label/value pairs | Two-column presentation, maximum ten fields, 2,000 characters per field. Check narrow rendering. |
+| `section` | Short explanation, optionally with an accessory | Text maximum 3,000 characters. `expand` controls text expansion; verify behavior for the app and surface. |
+| `markdown` | Longer generated report with headings, lists, code, or tables | Standard Markdown. Cumulative 12,000 characters per payload. Slack may translate it into several blocks. Image syntax produces links, so use a separate chart block. Verify app support and safe links. |
+| `rich_text` | Formatted prose with literal dynamic values and explicit link boundaries | Keep element styles explicit. Use the styles supported by each element. |
+| `image` | Chart, photograph, or illustration | Provide useful alternative text. A Slack file reference needs file access for the viewer. Do not shrink a chart into an accessory merely to fit a card. |
+| `actions` | Buttons and menus | Preserve interaction identifiers and menu choices when editing a payload. Do not assume card actions accept the same elements. |
+| `context` | Secondary attribution or source details | Keep critical values and required actions in the main content. |
+| `alert` | Colored informational or warning banner in a modal | Slack documents this block as modal-only. Do not copy it into a channel message. |
+| `task_card` | A real task or investigation step, with details, output, and sources | States are `in_progress`, `complete`, and `error`. An ongoing state needs an update path. |
+| `carousel` | Optional compact source or result cards | Do not hide required findings, charts, or controls behind horizontal navigation. |
+
+| `table` | Small comparison or report with repeated rows | Up to 100 rows and 20 columns; 10,000 characters across table cells per message. Supports rich-text, raw-text, and raw-number cells, column alignment, and wrapping. |
+| `data_table` | Repeated rows that need sorting, pagination, filtering, or row actions | Required caption and header row; up to 200 data rows plus header, 20 columns, and 20,000 characters across table cells per message. Default page size is five. Use numeric cells for numeric sorting. |
+
+Card text fields use text objects in Slack's examples, despite the reference table describing them as strings.
+Card `actions` is an array of buttons in the example payload. Check the actual example and API, not only the field table.
+
+## Choose prose, fields, or a table
+
+- For one finding, use a short sentence with selective emphasis. A table or scattered label/value columns adds work for the reader.
+- For independent metadata, use paired fields when the narrow layout remains readable.
+- For several comparable items, compare `table` and `data_table` with the same data.
+- Prefer `table` when all rows should be easy to scan without paging or row actions.
+- Consider `data_table` when sorting, paging, filtering, or a row action helps the task.
+- Keep the most important finding visible outside a paginated table. Its default five-row page can hide other results.
+- Keep numbers numeric for sorting; do not use a rich-text code cell if it changes numeric sorting into alphabetical sorting.
+- Data-table header cells cannot use `rich_text`. Action cells require buttons and can provide a text or number fallback.
+- Action cells are specific to `data_table`. Copied or shared data-table action buttons are disabled.
+- Check API acceptance, supported surface, desktop and narrow rendering, and action handling separately.
+
+The table comparison is based on Slack's references. It is not proof that either component passed a live application delivery test.
+
+## Patterns from Slack's templates
+
+Inspect the current [template gallery](https://app.slack.com/block-kit-builder/templates) when a visual example helps.
+
+- **Deep Research Result:** opening section, native Markdown report, source cards in a carousel, secondary context.
+ Use its report hierarchy for investigation results. Keep required evidence visible outside a carousel.
+- **Markdown Preview:** headings, emphasis, tables, lists, task lists, code, quotations, and links in a native Markdown block.
+ Use it to check text conversion. A rendering demonstration does not establish a safe link policy.
+- **Notification with Actions:** card title, subtitle, short body, action buttons, then context.
+ Use it for a short result with context and a few actions. Keep longer content outside the card.
+- **Itinerary:** header, dividers, paired fields, labeled groups, and short sections.
+ The supplied template is a modal. Its section and field pattern can also inform messages with supported blocks.
+- **Alerts:** alert banners and compact cards separated by dividers.
+ The supplied template is a modal. Reuse the hierarchy in messages, but not its modal-only alert block.
+
+## Official references
+
+- [Card](https://docs.slack.dev/reference/block-kit/blocks/card-block/)
+- [Container](https://docs.slack.dev/reference/block-kit/blocks/container-block/)
+- [Container fields in the official Python SDK](https://docs.slack.dev/tools/python-slack-sdk/reference/models/blocks/blocks.html)
+- [Section and expansion](https://docs.slack.dev/reference/block-kit/blocks/section-block/)
+- [Markdown](https://docs.slack.dev/reference/block-kit/blocks/markdown-block/)
+- [Alert and surface restriction](https://docs.slack.dev/reference/block-kit/blocks/alert-block/)
+- [Task card](https://docs.slack.dev/reference/block-kit/blocks/task-card-block/)
+- [Task streaming and display modes](https://docs.slack.dev/changelog/2026/02/11/task-cards-plan-blocks/)
+
+- [Simple table](https://docs.slack.dev/reference/block-kit/blocks/table-block/)
+- [Data table](https://docs.slack.dev/reference/block-kit/blocks/data-table-block/)
+
+## Sources and attribution
+
+This skill adapts the workflow in Slack's official [Block Kit skill](https://github.com/slackapi/slack-skills-plugin/blob/main/skills/block-kit/SKILL.md), including surface selection, live schema discovery, modification preservation, validation, and visual checks.
+Its selection guidance also draws on Slack's [design principles](https://github.com/slackapi/slack-skills-plugin/blob/main/skills/block-kit/references/design-principles.md) and [data-display guide](https://github.com/slackapi/slack-skills-plugin/blob/main/skills/block-kit/references/data-display-design.md).
+Reviewed revision: `2c95c4c0fc03a81bb0f15da802ed754dc6d46a8f`, 2026-10-26.
+The local workflow is self-contained and does not require the upstream plugin to be installed.
+Slack's repository uses the [MIT license](https://github.com/slackapi/slack-skills-plugin/blob/2c95c4c0fc03a81bb0f15da802ed754dc6d46a8f/LICENSE).