slack

Slack の運用

このスキルを使うと、Slack Web API を通じて Slack のデータ（チャンネル、メッセージ、スレッド、検索、ファイル、Webhook 署名検証）を読み取り、明示的な確認を得たうえで書き込めます。これは Slack プラットフォーム向けのツールスキルです。Slack アプリやボットの構築はアプリケーション開発にあたり、ワークスペースの管理（ユーザーのプロビジョニング、組織レベルの設定、SSO）は Slack の管理コンソールで行います。このスキルが担うのは日常的なエージェントのワークフローです。何が話されたかを把握し、あとから見つけ、担当者の確認を得て返信を投稿します。

運用上の契約

1. 変更を加える前に、読み取り専用で情報を確認します。 チャンネルの一覧表示、履歴の読み取り、スレッドの確認、検索、ファイルの一覧表示は自由に行えます。同梱の slack-cli スクリプトは書き込みを行わずに読み取りを実行します。
2. 操作の前に、対象、範囲、ロールバック方法を確認します。 メッセージの送信やスレッドへの返信は、ワークスペースを共有する全員に見える状態を変更するため、チャンネルを指定した担当者からの明示的な指示が必要です。また、slack-cli で --dry-run によるプレビューと --yes による確認を行う必要があります。チームメンバーがすでに読んだメッセージを「送信取り消し」することはできません。
3. 読み取りの範囲を守ります。 Slack のデータはページ分割されます。タスクに必要な範囲を超えてページを取得しないでください。slack-cli --limit N はすべての一覧表示の件数を制限し、レスポンスでは生のペイロードをすべて出力せず、レコードの概要を示します。
4. Webhook を信頼する前に検証します。 Slack イベントを受け付けるハンドラーはすべて、アプリの署名シークレットを使って X-Slack-Signature と X-Slack-Request-Timestamp を検証する必要があります。検証しなければ、エンドポイントにアクセスできる誰もがイベントを偽造できてしまいます。slack-cli webhook verify で検証できます。
5. 証拠の共有は必要な範囲にとどめます。 メッセージの短い抜粋と ID を引用してください。スレッド全体、トークン、ファイルの内容をチャットに貼り付けないでください。

slack-cli スクリプト

scripts/slack-cli は、標準ライブラリのみを使う、エージェント向けの Slack Web API CLI です。メッセージ、チャンネル、スレッド、検索、ファイル、Webhook 検証を含む、この課題の範囲全体を扱います。

slack/scripts/slack-cli --help                          # no token or network needed
slack/scripts/slack-cli --json --limit 10 channels list
slack/scripts/slack-cli --json messages list --channel C12345
slack/scripts/slack-cli --json threads list --channel C12345 --ts 1712345678.000001
slack/scripts/slack-cli --json search messages --query "incident"
slack/scripts/slack-cli --json files list --limit 5
slack/scripts/slack-cli messages send --channel C12345 --text "on it" --dry-run   # preview
slack/scripts/slack-cli messages send --channel C12345 --text "on it" --yes       # confirmed
slack/scripts/slack-cli webhook verify --body-file body.json --signature "v0=..." --timestamp 1712345678

終了コード：0 は成功、1 は API エラーまたは検証失敗、2 は使用方法のエラーです。送信にはガードが設けられています。--dry-run または --yes が指定されていない場合、スクリプトは送信を拒否し、終了コード 1 を返して、API を呼び出しません。読み取り件数は --limit（デフォルト 20、最大 100）で制限されます。

運用の流れ

1. ワークスペースで対象範囲を定めます：関連するチャンネル、質問の内容（何が、誰によって、いつ話されたか）、および何らかの操作が変更にあたるかを確認します。
2. 範囲を絞って読み取ります：channels list で ID を確認し、messages list／threads list で履歴を取得し、search messages で複数チャンネルを横断して検索します。いずれも読み取り専用です。
3. 回答に必要な情報を整理します：質問と証拠を対応付けます（文脈はスレッドの返信、正確な語句は検索、共有された資料はファイル一覧で確認します）。
4. 確認を得て操作します：担当者から送信の指示があった場合に限り、--dry-run でプレビューし、--yes で確認します。
5. 検証します：投稿後はレスポンス内のメッセージ ts とチャンネルを確認します。Webhook の場合は、イベントを信頼する前に署名検証の結果を確認します。

メッセージ、チャンネル、スレッド

• チャンネル（conversations.list）：パブリックおよびプライベートのチャンネル、アーカイブ状態、メンバー数を取得します。チャンネル ID（C...）は他のすべての呼び出しで使う固定キーです。使用前に名前から ID を特定してください。
• メッセージ（conversations.history）：チャンネル内の履歴を新しい順に、一度に 1 ページ取得します。メッセージレコードには ts（ID）、user、text が含まれます。意図的にページを取得する場合は、レスポンスのメタデータにある --cursor を使用してください。
• スレッド（conversations.replies）：親メッセージの ts をキーに返信を取得します。親メッセージは最初の結果として返されます。スレッド内の返信では、thread_ts に親メッセージの値が設定されます。
• 送信（chat.postMessage）：このスキルの対象範囲における唯一の変更操作です。必ず --dry-run でプレビューし、--yes で確認してください。新しいメッセージを開始する代わりにスレッドへ返信する場合は、--thread-ts を指定してください。返された ts とチャンネルを確認します。

検索とファイル

• 検索（search.messages）：Slack の検索構文（from:、in:、引用符で囲んだフレーズ、before:／after:）を使って、閲覧可能な履歴全体を全文検索します。結果には一致したチャンネルが含まれます。total は一致件数を示し、matches は --limit の範囲内に制限されます。
• ファイル（files.list）：ワークスペースで共有されたファイルを、チャンネルまたはユーザーで絞り込み、パーマリンクとサイズとともに取得します。ファイルの 内容 のダウンロードは CLI の対象外です（読み取り量に制限があります）。ファイルを見つけるために使用し、人間から内容を求められた場合は、認証済みリクエストでパーマリンクを取得してください。

Webhook の検証

Slack は、イベント／コマンド／インタラクティビティの各エンドポイントへのすべての HTTP リクエストに署名します。検証手順は次のとおりです。

1. 生のリクエストボディを取得します（受信したままの状態で使用し、再エンコードしないでください）。
2. X-Slack-Request-Timestamp が現在時刻から約 5 分以内であることを確認します（リプレイ攻撃対策）。
3. v0=HMAC_SHA256(signing_secret, "v0:" + timestamp + ":" + body) を計算し、定時間比較を使って X-Slack-Signature と照合します。
4. タイムスタンプが古い場合、または署名が一致しない場合は、401 を返します。

slack-cli webhook verify --body-file body.json --signature "v0=..." --timestamp <unix> は、SLACK_WEBHOOK_SECRET（または --secret）を使ってこの検証をそのまま実行し、定時間比較で検証された結果を報告します。イベントペイロードを信頼する前に、必ず検証してください。検証されていない Webhook エンドポイントは、偽造されたイベントを受け入れてしまいます。

リファレンスの参照先

読み込むタイミング	リファレンス
ソース、スコープの表、更新手順	references/00-source-index.md
API メソッドの一覧、ページネーション、スコープ、Webhook 検証の詳細	references/01-web-api-operations.md

同梱アーティファクト

• scripts/slack-cli：処理範囲を制限した、標準ライブラリのみを使う CLI（メッセージ、チャンネル、スレッド、検索、ファイル、Webhook 検証、--json、--limit。送信には --dry-run／--yes が必要です）。
• tests/test_slack_cli.py：ミューテーションゲートと読み取り専用の契約を含む、スタブ Slack API に対する再現性のある 16 件のテスト。
• references/：日付入りのソースインデックスと Web API 操作リファレンス。
• evals/evals.json：エージェントの実行を評価する、出力品質に関する 6 件のケース。

検証の境界

主張	最低限の証拠
チャンネルが存在し、その名前が分かっている	slack-cli channels list --json がそのチャンネルと C... ID を返す
メッセージが送信された	slack-cli messages send --yes が新しい ts とチャンネルを返し、messages list にそのメッセージが表示される
検索で一致結果が見つかった	slack-cli search messages --query "..." --json が total_matches と、件数が制限された一致結果を返す
Webhook が正規のものである	正確なボディ／署名／タイムスタンプに対して slack-cli webhook verify が終了コード 0 で終了し、verified: true を返す
ファイルが存在する	slack-cli files list --json がその F... ID とパーマリンクを返す

厳守すべき制限

• 人間からの指示、--dry-run によるプレビュー、--yes による確認なしに、メッセージやスレッドへの返信を送信しないでください。Slack の投稿は公開され、永続的で、取り消しても相手の画面から消えるとは限りません。
• 署名とタイムスタンプを検証せずに、受信した Webhook を信頼しないでください。
• --limit を超えて読み取りをページングしないでください。スレッド全体、トークン、ファイルの内容をチャットに出力しないでください。
• このスキルは Slack Web API を操作します。Slack アプリの構築（アプリケーション開発）、ユーザーや組織の設定の管理（管理コンソール）、または他のチームチャットプラットフォームには対応していません。それぞれに専用のツールがあります。

使用しない場合

• Slack アプリやボットの構築（Block Kit、Bolt、スラッシュコマンドアプリ、OAuth フローの設計）：これはアプリケーション開発です。サービス設計については backend-engineering を参照してください。
• ワークスペースの管理（ユーザーのプロビジョニング、デプロビジョニング、組織レベルの設定、SSO／SAML、組織レベルでのデータエクスポート）：これは Slack 管理コンソールの領域であり、Web API の対象ではありません。
• その他のチームチャットプラットフォーム（Discord、Mattermost、Teams）：それぞれに専用のツールがあり、このスキルは Slack のみを対象とします。
• メッセージングやチャンネル管理に関する全社ポリシー：これは組織のポリシーであり、API 操作ではありません。