: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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.mdindex 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.mdindex 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, breWhen 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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).