block-kit

Block Kit

開発者がリッチな Block Kit レイアウトを作成できるよう支援します。$0 が厳密に message、modal、または home-tab のいずれかであれば、それを対象サーフェスとして扱います。それ以外の場合（空の場合や他の値の場合も含む）は無視し、Step 1 でサーフェスを特定します。

このスキルでは、サーフェスの選択、レイアウトの計画、JSON の生成、検証を順に進めます。ブロックタイプ、要素、フィールドはライブドキュメントに記載されています（以下の信頼できる情報源を参照）。ドキュメントで項目を確認し、各コンポーネントのスキーマを読んでください。記憶を頼りにしてはいけません。

よくある Block Kit の間違い（その理由）： 事前に注意を促すべきほど頻繁に起きるエラーがいくつかあります。それ以外の多くのエラーは Step 5 の blocks.validate で検出されるため、ルールを暗記するより検証を活用してください。

• "type": "text" は存在しません。 テキストはコンポジションオブジェクトです。{ "type": "plain_text", "text": "..." } または { "type": "mrkdwn", "text": "..." } を使用します。
• markdown はテキストタイプではなく、_ブロック_タイプです。 markdown ブロックには標準の Markdown を記述します。他のブロック内のテキストオブジェクトでは mrkdwn を使用します（Step 4 のmrkdwn と markdown ブロックの違いを参照）。Slack の mrkdwn では、**bold** ではなく *bold* / _italic_ / ~strike~ を使います。
• メッセージには、トップレベルの text フォールバックが必要です。 blocks.validate はこれがないことを検出しませんが、通知やスクリーンリーダーではブロックの代わりにこのテキストが表示されます。そのため、空のままにせず、レイアウトで伝える内容を要約してください。

---

信頼できる情報源：ライブドキュメント

すべてのブロック、要素、コンポジションオブジェクトは docs.slack.dev に記載されています。任意のリファレンス URL の末尾に .md を追加すると、WebFetch を使って Markdown として取得できます（認証不要）。

• マスターインデックス：すべてのブロック、ブロック要素、コンポジションオブジェクトの信頼できる一覧です。それぞれの項目から専用ページにリンクしています。https://docs.slack.dev/reference/block-kit.md を WebFetch で取得し、タイプが存在することを確認して専用ページへのリンクを取得してください。
• コンポーネントごとのページには、フィールドスキーマ全体（必須／任意のフラグと制約を含むフィールド表、および JSON の例）が記載されています。
  • ブロック：https://docs.slack.dev/reference/block-kit/blocks/<slug>-block.md
  • ブロック要素：https://docs.slack.dev/reference/block-kit/block-elements/<slug>-element.md
  • コンポジションオブジェクト：https://docs.slack.dev/reference/block-kit/composition-objects/<slug>.md
• slug が常にタイプ名と同じとは限りません。 たとえば、datepicker は date-picker-element.md に対応します。また、すべての *_select メニュー（static_select、users_select、multi_channels_select など）は select-menu-element.md に記載されています。slug がわからない場合は、URL を手作業で組み立てず、マスターインデックスのリンクをたどってください。
• サーフェスのペイロード構造はサーフェスガイドに記載されています。メッセージは https://docs.slack.dev/messaging/formatting-message-text.md、モーダルは https://docs.slack.dev/surfaces/modals.md、Home タブは https://docs.slack.dev/surfaces/app-home.md を参照してください。

ライブページで確認していないブロックタイプ、要素、フィールドは決して使用しないでください。

---

クイックパス（明確で具体的なリクエストの場合）

開発者のリクエストから対象サーフェスと希望するレイアウトの両方を特定できるほど具体的な場合は、Step 1〜4 をまとめて一度に進めます。

1. $0 または文脈からサーフェスを特定する
2. 言及されているブロックと要素のドキュメントページだけを取得する
3. JSON を直接生成する
4. Step 5（検証）に進む

クイックパスを使う目安（全ワークフローを省略）：

• 開発者が変更対象の既存 JSON を提示している → 代わりに変更モードを使用する
• 開発者が特定のブロックタイプを指定している：「2 つのボタンがある actions ブロックを追加する」
• 開発者がよく知られたパターンを説明している：「承認メッセージ」、「フィードバックフォーム」、「設定モーダル」
• 開発者が 1 つのメッセージで、作成に十分な詳細を含む完全な説明を提示している

全ワークフローを使う目安（Step 1〜7 を使用）：

• 曖昧なリクエスト：「何かクールなものを作って」、「ダッシュボードを作って」
• 探索的なリクエスト：「Block Kit で何ができますか？」、「選択肢を教えて」
• 複雑なレイアウト：ブロックが 10 個以上、入れ子になったモーダル、条件分岐
• 開発者が何を作るか相談している

変更モード

開発者が既存の Block Kit JSON を（インラインで貼り付ける、ファイル内に置く、またはコードから参照するなどして）提供した場合は、通常の作成ワークフローではなく、変更モードに入ります。

1. 既存の構造を解析する：

   • 各ブロックについて、インデックス、種類、内容の簡単な説明を一覧表示します
   • 表示先を推定します。"type": "modal" = モーダル、"type": "home" = ホームタブ、blocks 配列のみ = メッセージ

2. 希望する変更を尋ねる：

   • ブロックを追加する（シーケンスのどこに追加しますか？）
   • ブロックを削除する（どのブロックを削除しますか？）
   • ブロックを変更する（どのブロックを、どのように変更しますか？）
   • ブロックの順序を変更する

3. 次のものを保持しながら変更を適用する：

   • 既存の block_id の値（アプリのインタラクションハンドラーから参照されます）
   • 既存の action_id の値（イベントリスナーに対応します）
   • 変更しないブロックの既存のスタイル、テキスト内容、構造

4. 変更後の JSON を検証する：ステップ 5（検証）に進みます

検出： 開発者のメッセージに、[{"type": で始まる JSON 配列、または "blocks": を含むビューオブジェクトがある場合は、自動的に変更モードに入ります。既存のブロックに関連して「edit」「update」「modify」「change」と指示された場合は、現在の JSON を提供するよう依頼します。

---

ステップ 1：対象の表示先を決める

$0 が指定されており、message、modal、home-tab のいずれかに一致する場合は、それをそのまま使用します。

それ以外の場合は、AskUserQuestion を使って開発者に尋ねます。

• メッセージ：チャンネルまたは DM に投稿する会話形式のコンテンツ。最大 50 ブロック。
• モーダル：ユーザーの操作によって開くダイアログまたはフォーム。最大 100 ブロック。
• ホームタブ：App Home に表示する、ユーザーごとに保持されるダッシュボード。最大 100 ブロック。

表示先が決まったら、適切なペイロード構造を使用します。

• メッセージ：chat.postMessage（および関連メソッド）で投稿する { "text": "Fallback text", "blocks": [...] } オブジェクトです。text フィールドは通知やアクセシビリティ向けのフォールバックです。メッセージのテキスト書式（mrkdwn、メンション、日付）については、https://docs.slack.dev/messaging/formatting-message-text.md を参照してください。
• モーダル：ビューオブジェクト（{ "type": "modal", "title": ..., "blocks": [...] }）です。ビューオブジェクトの完全な構造とライフサイクル、およびビューに input ブロックが含まれる場合は submit が必須となるルールについては、https://docs.slack.dev/surfaces/modals.md を参照してください。
• ホームタブ：views.publish で公開するビューオブジェクト（{ "type": "home", "blocks": [...] }）です。構造と動作については、https://docs.slack.dev/surfaces/app-home.md を参照してください。

---

ステップ 2：作成するものを理解する

開発者に、作成したいレイアウトの見た目や目的を説明してもらいます。

アイデアが必要な場合は、次の例を提案します。いくつかは references/common-patterns.md にある既製テンプレートに直接対応しており（括弧内に記載）、ステップ 3 でそれを元に作成できます。

• 「テキスト入力とカテゴリ選択欄を備えたフィードバックフォーム」（シンプルなフォームモーダル）
• 「説明と次の手順ボタンを備えたデプロイ失敗の通知」（通知アラート）、または「承認／却下ボタンを備えた承認依頼」（承認メッセージ）
• 「ウェルカムヘッダー、フィールド内の主要指標、クイックアクションボタンを備えたダッシュボードのホームタブ」（ダッシュボードホームタブ）
• 「ドロップダウン、チェックボックス、時間選択を備えた設定モーダル」（複数の入力タイプを備えた設定モーダル）
• 「ステータスとポイントを含むスプリントタスクの表」（データテーブル）
• 「太字テキスト、リンク、箇条書きを含むデプロイ概要」（リッチテキストセクション）
• 「編集／複製／削除操作用の行レベルの『⋯』メニュー」（オーバーフローメニュー付きの行アクション）
• 「画像、価格、カートに追加ボタンを備えた商品カード」（カードプレビュー）

JSON を生成する前に、レイアウトを計画するのに十分な詳細を確認します。

---

ステップ 3：ブロックのレイアウトを計画する

開発者の説明に基づいて、以下を行います。

1. ライブドキュメントから必要な情報だけを取得します。

   • WebFetch でマスターインデックス（https://docs.slack.dev/reference/block-kit.md）を取得し、使用予定のブロックと要素の種類が存在することを確認して、それぞれのページへのリンクを取得します。
   • デザインの適切さについては references/design-principles.md を参照します。コンテンツの形状に合うブロック（表と縦に並べたセクション、カードと個別のブロックなど）、強調、読み進める順序、アクセシビリティを確認します。ここでは、レイアウトが適切で読みやすいかを判断するための指針を示しており、有効性を判断するものではありません。レイアウトに応じて、以下も参照します。
     • モーダルとフォームについては references/modal-design.md を参照します。タイトルと送信ラベル、入力ラベルとヒント、複数ステップのフロー、検証エラー、読み込み中や成功時の状態を確認します。
     • Home タブについては references/home-tab-design.md を参照します。最上部に表示する内容、空の状態と初回起動時の状態、ビューを最新に保つ方法、役割ごとの異なるビュー、エージェント向けのレビュー画面を確認します。
     • 数値とレコードについては references/data-display-design.md を参照します。section のフィールド、table、data_table、data_visualization チャートの使い分けと、それぞれを明確に表示する方法を確認します。
     • エージェントの作業を表示する場合は references/agent-progress-design.md を参照します。plan ブロックや task_card ブロック、またはストリーミングされるタスク更新を確認します。
     • 承認ゲート、1 つのメッセージで複数の提案済みアクションを承認する方法、選択肢の明確化、送信前の編集については references/human-in-the-loop.md を参照します。
   • 依頼が一般的なパターンに当てはまる場合は references/common-patterns.md を確認し、最初から作成するのではなくテンプレートを使用します。
   • 個々のコンポーネントのページを読むのはステップ 4 まで後回しにします。ステップ 4 で各ブロックのフィールドを組み立てます。

2. 番号付きのブロック概要を提案します。例：

   1. header: "Weekly Report"
   2. section: Summary text with a datepicker accessory
   3. divider
   4. section: Status fields (Name, Role, Team)
   5. actions: "Approve Report" button (primary) and "Reject" button (unstyled)
   

3. JSON を生成する前に、概要を開発者に提示し、承認または変更を依頼します。

サーフェスの制約事項：

• ブロック数の上限：メッセージでは 50、モーダル／Home タブでは 100
• モーダル固有：input ブロックを使用する場合、モーダルのペイロードに submit フィールドを含める必要があります
• テーブル：1 つのメッセージにつき table ブロックは 1 つのみ
• チャート：1 つのメッセージにつき data_visualization ブロックは最大 2 つ
• アラート：alert ブロックはモーダルでのみ使用できます。メッセージでは、header または section で重大度を言葉で示します。
• サーフェスとの互換性（選択したサーフェスでブロックが有効かどうか）と要素との互換性（特定のブロック内で要素を使用できるかどうか）は、コンポーネントのドキュメントページに記載されていない場合があります。これらについては references/design-principles.md のサーフェスと制限の表を確認してください。ステップ 5 の blocks.validate では、これらの互換性は検証されません。ブロックと要素の形状のみを検証するため、間違ったサーフェスでのブロックや個数上限を超えたブロックでも ok: true が返されます。検証に合格したことを、サーフェスや個数の制約を満たしている確認として扱わないでください。

---

Step 4: Block Kit JSON を生成する

レイアウトが承認されたら、各ブロックのライブドキュメントページからブロックを構築します。WebFetch を使って各ページのフィールド表（必須か任意か、制約）と JSON の例を取得してください。URL のパターンは上記の信頼できる情報源にあります。覚えておくべきスラッグは、すべての *_select メニュー（static_select、users_select、multi_channels_select、…）が select-menu-element.md に記載されていることです。必要に応じてページを取得し、すでに取得した情報は再利用してください。同じ種類のブロックごとに同じページを再取得しないでください。その後、ペイロードをブロックごとに構築し、Step 1 のサーフェス構造で囲みます。

ガイドライン：

• 説明的な action_id の値を使用します（例："action_1" ではなく "approve_report_btn"）。これらの値はインタラクションハンドラーで要素を識別するために使われます
• インタラクション処理で開発者が必要とする箇所には block_id の値を含めます
• モーダルには title、submit、close、callback_id を含めます。ホームタブには type: "home" のラッパーを含めます
• リッチな書式設定には mrkdwn テキストを使い、必須の箇所（ヘッダー、ラベル、モーダルタイトル）には plain_text を使います

mrkdwn と markdown ブロックの違い： section ブロックと context ブロックでは、Slack の mrkdwn（**bold** ではなく *bold*）でテキストを整形します。別個の markdown ブロック（メッセージのみ）は標準的な Markdown をレンダリングするもので、すでに標準的な Markdown 形式になっている AI／LLM 生成コンテンツや長文コンテンツ向けです。references/design-principles.md の**「テキスト：rich_text、mrkdwn、markdown ブロック」**では、コード内で作成する書式付きテキストに rich_text を使う場合も含め、それぞれをいつ使うべきかを説明しています。

アクセシビリティは見落としやすく、後から追加するのが難しいため、今のうちに組み込んでください。各ブロックを作成する際は、references/design-principles.md の**「アクセシビリティとフォールバック」**を適用してください。text のフォールバック、alt_text、色と絵文字、ボタンラベル、表やグラフのテキストによる代替について説明しています。

完全なペイロードを Step 1 のサーフェス構造で開発者に提示します。

---

Step 5: 検証する

必ず検証してください。 blocks.validate は公開 Web API メソッドなので、認証トークンは必要ありません。

このメソッド（パラメーター、認証要件、レスポンス／エラーの形式）に関する正式なリファレンスはライブドキュメントです。ここに記載されている内容を頼りにする前に、WebFetch で取得してください：https://docs.slack.dev/reference/methods/blocks.validate.md。このドキュメントでは、受け付けるパラメーター（メッセージのブロック配列には blocks、モーダル／ホームタブのビューには view、完全なメッセージペイロードには message。いずれか 1 つだけを指定）とレスポンス形式が説明されています。

5a. 検証リクエストを作成する

Slack CLI が利用できる場合は、slack-cli スキルの CLI 検出機能を再利用でき、トークンの扱いも不要なため、Slack CLI を優先してください。CLI がインストールされていない場合は、curl に切り替えます。どちらも同じ公開メソッドを呼び出して同じレスポンスを返すため、どちらの場合も Step 5b を適用します。

パス A：Slack CLI（推奨）。

slack:slack-cli スキルのStep 1: Slack CLI を検出するを使って、公開 CLI がインストールされているか確認し、そのコマンド（SLACK_CMD）を特定します。

CLI を利用できる場合は、slack:slack-cli スキルのStep 4: Web API メソッドを呼び出す（slack api）を使って実行します。このステップでは、SLACK_CMD api <method> key=value … の構文を説明しています。まず SLACK_CMD api --help を実行し、構文と認証をスキップするフラグを確認してください。blocks.validate にはトークンが不要なので、認証なしで呼び出します。フラグの名前が変更された場合にも正しく対応できるよう、記憶に頼ってフラグを決めず、ヘルプの出力を確認してください。ペイロードは位置引数の key=value として渡します。メッセージの場合は blocks=<JSON array>、モーダルとホームタブの場合は view=<JSON view object> を指定します。

パス B：curl（CLI がインストールされていない場合の代替）。

Bash ツールを使ってエンドポイントに POST します。API は form-urlencoded エンコーディングを使用するため、JSON をパラメーターの値として直接渡します。

メッセージの場合は、blocks 配列を form-encoded パラメーターとして送信します。

curl -s -X POST 'https://slack.com/api/blocks.validate' \
  -d 'blocks=[ ... the blocks array ... ]'

モーダルとホームタブの場合は、完全なビューオブジェクトを view フィールドに送信します。

curl -s -X POST 'https://slack.com/api/blocks.validate' \
  -d 'view={ "type": "modal", "title": ..., "blocks": [...] }'

5b. レスポンスを処理する

成功：

{ "ok": true }

ブロックが有効であることを開発者に伝えます。

失敗：

{
  "ok": false,
  "error": "invalid_blocks",
  "errors": [
    {
      "code": "missing_field",
      "message": "missing required field: type",
      "field": "type",
      "pointer": "/0"
    }
  ]
}

検証に失敗した場合：

1. 各エラーを読みます。pointerは問題があるノードを指すJSONポインターです（例：/0＝最初のブロック、/2/elements/1＝3番目のブロックの2番目の要素、/0/text/type＝最初のブロックのtextオブジェクトのtypeフィールド）。messageは問題の説明で、constraint（存在する場合）は失敗したルールと期待値を示します。
2. JSONを修正します。エラーコードの正式な意味とフィールド要件については、ライブメソッドドキュメント（https://docs.slack.dev/reference/methods/blocks.validate.md）およびStep 3〜4で取得した関連するブロック／要素／コンポジションオブジェクトのページを参照してください。
3. 再検証します。"ok": trueになるまで繰り返します。

---

Step 6: 最終出力を提示する

検証済みのペイロードを提示し、開発者が利用できるようサポートします。

送信する

ペイロードの構築はこのスキルの役割です。送信（chat.postMessage、views.open、views.publishおよびそれらに関連するトークン／スコープの処理）はWeb APIレイヤーの役割です。Slack CLI、素のcurl、Bolt SDKのいずれかを使って適切なメソッドを呼び出すには、このペイロードをメソッドのblocks引数（メッセージの場合）またはview引数（モーダルとホームタブの場合）として渡し、slack:slack-apiスキルの**Step 4: Call the Method (Manage)**を使用します。このスキルは引数名をSDKまたはHTTP呼び出しに対応付けるため、ここで重複して説明する必要はありません。

プレビューする

Block Kit Builderでレイアウトを確認できるよう、開発者をサポートします。Slack CLIがインストールされている場合は、そちらを優先します。CLIはブロックを自動的に読み込むため、開発者がコピー＆ペーストする必要はありません。CLIが利用できない場合は、標準のBuilderリンクを提示します。

Path A: Slack CLI（優先）。

slack:slack-cliスキルのStep 1: Detect the Slack CLIを使用して、公開CLIがインストールされているかを確認し、そのコマンド（SLACK_CMD）を特定します。

CLIが利用可能な場合は、SLACK_CMD blocks preview --helpを実行し、ブロックを渡してプレビューを開く方法を確認します。このコマンドはブロックを開発者のブラウザーでBlock Kit Builderに読み込みます。

CLIを非対話形式で実行するため、このコマンドには--teamフラグも必要です。slack:slack-cliスキルのStep 2: Command Discovery via Helpを使ってチームIDを特定してください。「Resolving --app and --team values」のガイダンスに従い、SLACK_CMD auth listを実行します。プレビューには認証済みのワークスペースであればどれでも使えます。複数ある場合は1つ選び、選択の確認を求めずに、どれを使用したかを伝えてください。

Path B: Block Kit Builderのリンク（CLIがインストールされていない場合の代替）。

開発者がJSONを貼り付けて視覚的に調整できるよう、Block Kit Builderのリンクを提示します。https://app.slack.com/block-kit-builderを使用します。Builderには、配列だけでなくオブジェクト（{ "blocks": [...] }またはビュー全体のオブジェクト）が必要です。

---

Step 7: 反復する

ブロックの追加、変更、削除、並べ替え、または別のサーフェス向けのレイアウト作成を希望するか、開発者に尋ねます。作成したレイアウトの変更を希望する場合は、Modification Modeに戻ります（開発者のblock_id／action_id値を保持します）。新しいレイアウトを作成する場合は、Step 3に戻ります。

---

Notes

• **範囲：**このスキルは、Block Kitペイロードの構築と検証（サーフェスの選択、ライブドキュメントに基づくJSONの作成、blocks.validateによる確認）を担当します。送信はWeb APIレイヤー（slack:slack-api）の役割で、CLIの検出と認証はslack:slack-cliの役割です。
• blocks.validateに認証は不要です。公開メソッドであるため、CLIまたはcurlのどちらから呼び出しても、トークンなしで動作します。確定する前に必ず検証してください（Step 5）。