## Recognition

- "slack", "post to channel", "DM", "message the team", "announce"
- Quick internal communication
- Real-time or near-real-time context

## Format Selection

| Use | When |
|-----|------|
| Block Kit JSON | Announcements, structured updates, anything needing visual hierarchy, metrics, or actions |
| Plain mrkdwn | Quick replies, thread responses, simple one-liners |

**Default to Block Kit** for any substantive message. Output valid JSON that can be pasted into Slack's Block Kit Builder or sent via API.

---

## Block Kit Structure

Every Block Kit message is a JSON object with a `blocks` array:

```json
{
  "blocks": [
    { "type": "header", ... },
    { "type": "section", ... },
    { "type": "divider" },
    { "type": "context", ... }
  ]
}
```

---

## Block Types

### Header
Top-level title for the message.

```json
{
  "type": "header",
  "text": {
    "type": "plain_text",
    "text": "🚀 Release v2.4.0 Shipped",
    "emoji": true
  }
}
```

### Section
Primary content block. Supports mrkdwn text and optional accessory (button, image, etc).

```json
{
  "type": "section",
  "text": {
    "type": "mrkdwn",
    "text": "*What's new:*\n• Faster search indexing\n• Dark mode support\n• Bug fixes for auth flow"
  }
}
```

With accessory button:

```json
{
  "type": "section",
  "text": {
    "type": "mrkdwn",
    "text": "Review the changes before merging."
  },
  "accessory": {
    "type": "button",
    "text": { "type": "plain_text", "text": "View PR", "emoji": true },
    "url": "https://github.com/org/repo/pull/123"
  }
}
```

### Divider
Visual separator between sections.

```json
{ "type": "divider" }
```

### Context
Small metadata line (timestamps, authors, tags).

```json
{
  "type": "context",
  "elements": [
    { "type": "mrkdwn", "text": "Posted by <@U123ABC> • Dec 5, 2024" }
  ]
}
```

### Actions
Row of interactive buttons.

```json
{
  "type": "actions",
  "elements": [
    {
      "type": "button",
      "text": { "type": "plain_text", "text": "Approve", "emoji": true },
      "style": "primary",
      "action_id": "approve_action"
    },
    {
      "type": "button",
      "text": { "type": "plain_text", "text": "Reject", "emoji": true },
      "style": "danger",
      "action_id": "reject_action"
    }
  ]
}
```

### Image
Standalone image block.

```json
{
  "type": "image",
  "image_url": "https://example.com/chart.png",
  "alt_text": "Weekly metrics chart"
}
```

---

## Templates

### Announcement

```json
{
  "blocks": [
    {
      "type": "header",
      "text": { "type": "plain_text", "text": "📢 [Title]", "emoji": true }
    },
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "[Main announcement body with *bold* for emphasis]" }
    },
    { "type": "divider" },
    {
      "type": "context",
      "elements": [
        { "type": "mrkdwn", "text": "Questions? Reply in thread 👇" }
      ]
    }
  ]
}
```

### Status Update with Metrics

```json
{
  "blocks": [
    {
      "type": "header",
      "text": { "type": "plain_text", "text": "📊 Weekly Metrics", "emoji": true }
    },
    {
      "type": "section",
      "fields": [
        { "type": "mrkdwn", "text": "*Active Users*\n12,450 (+8%)" },
        { "type": "mrkdwn", "text": "*Revenue*\n$84.2K (+12%)" },
        { "type": "mrkdwn", "text": "*Churn*\n2.1% (-0.3%)" },
        { "type": "mrkdwn", "text": "*NPS*\n72 (+5)" }
      ]
    },
    { "type": "divider" },
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "*Highlights:* Strong week driven by product launch. Retention up across all cohorts." }
    },
    {
      "type": "context",
      "elements": [
        { "type": "mrkdwn", "text": "Week of Dec 2–8, 2024 • " }
      ]
    }
  ]
}
```

### Action Prompt

```json
{
  "blocks": [
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "🙋 *Need approval:* Budget request for Q1 marketing spend ($25K)" }
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "✅ Approve", "emoji": true },
          "style": "primary",
          "action_id": "approve"
        },
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "❌ Reject", "emoji": true },
          "style": "danger",
          "action_id": "reject"
        },
        {
          "type": "button",
          "text": { "type": "plain_text", "text": "View Details", "emoji": true },
          "url": "https://docs.example.com/budget-q1"
        }
      ]
    }
  ]
}
```

### Team Update

```json
{
  "blocks": [
    {
      "type": "header",
      "text": { "type": "plain_text", "text": "🏃 Sprint 14 Wrap-up", "emoji": true }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Completed:*\n• User onboarding redesign\n• API rate limiting\n• Mobile push notifications\n\n*Carried over:*\n• Dashboard export feature (blocked on design)"
      }
    },
    { "type": "divider" },
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "*Next sprint focus:* Performance optimization and Q1 planning" }
    },
    {
      "type": "context",
      "elements": [
        { "type": "mrkdwn", "text": "Sprint 14 • Nov 25 – Dec 6 • Team: Platform" }
      ]
    }
  ]
}
```

---

## mrkdwn Reference

For text within blocks, use Slack's mrkdwn syntax:

| Element | Syntax |
|---------|--------|
| Bold | `*bold*` |
| Italic | `_italic_` |
| Strike | `~strikethrough~` |
| Code | `` `inline code` `` |
| Code block | ` ```code block``` ` |
| Link | `` |
| User mention | `<@U123ABC>` |
| Channel | `<#C123ABC>` |
| Bullet list | `• item` (or `- item`) |

---

## Pitfalls

- Don't mix Block Kit with plain text in the same message—use one or the other
- `header` only accepts `plain_text`, not mrkdwn
- `fields` in section blocks max out at 10 items, 2 columns
- Button `style` only accepts `"primary"` (green) or `"danger"` (red)—omit for default gray
- Test in [Block Kit Builder](https://app.slack.com/block-kit-builder) before sending