slack-docs

Slack プラットフォームのドキュメント

開発者が公式の Slack ドキュメントサイト（https://docs.slack.dev）で適切なページを見つけ、読みやすい Markdown として読むことを支援します。これにより、回答を記憶ではなく最新のドキュメントに基づいて提供できます。このサイトには、エージェントが認証も Slack ワークスペースも不要で直接利用できる、機械可読な 3 つのインターフェースがあります。

• 検索 API メソッド：GET https://docs.slack.dev/api/v1/search?query=<q>&category=<c> は、ページの検索結果をランク順に JSON で返します。各検索には category（ガイド、リファレンス、特定の SDK など）を指定してください。カテゴリを指定しない検索は、SDK のページに大きく偏ります。
• ページごとの Markdown：すべてのページは、その URL に .md を付けた URL で利用できます（例：/quickstart.md）。
• インデックスファイル：/llms.txt（厳選された概要）と /llms-sitemap.md（すべての Markdown ページの一覧）。

$0 が指定されている場合、それが docs.slack.dev の URL ならファストパスに進み、トピックならステップ 1から検索します。特定のページではなく、「Slack で X を構築する方法を知りたい」という大まかな質問の場合は、まず https://docs.slack.dev/llms.txt を読みます。これは、プラットフォームの概要と推奨される構築手順をまとめた、LLM 向けに厳選された資料です。

重要なルール：

• ドキュメントが信頼できる情報源です。Slack プラットフォームに関する事実の質問には、記憶に頼って答えないでください。ページを見つけて取得し、記載内容に基づいて回答してください。
• ページを取得するときは、HTML 版よりも .md 版を優先してください。読み取りや引用に適しています。
• 取得したすべての Markdown ページの先頭には、Source: <url> の行があります。開発者にページを引用して示せるよう、その URL を保持してください。

禁止事項：

• ドキュメントの URL を作り出さないでください。検索 API、サイトマップ、または開発者から渡されたリンクから取得し、取得して確認してください。
• 実際に取得していないページの内容を言い換えないでください。取得に失敗した場合は、記憶で補わず、その旨を伝えてください。
• すべての URL に .md 版があると決めつけないでください。取得時にエラーが返された場合は、別の URL を推測するのではなく、検索 API またはサイトマップ（ステップ 1）を使ってください。

---

ファストパス（開発者がすでに URL を持っている場合）

開発者が https://docs.slack.dev/... のリンクを貼り付けた場合は、ページの探索を省略し、ステップ 2に進んで取得し、内容を読みます。

---

ステップ 1：ページを見つける（検索）

ドキュメントの検索 APIを使って候補ページを見つけます。クエリを URL エンコードし、結果の範囲を絞るための category を指定して、この URL を WebFetch します。

https://docs.slack.dev/api/v1/search?query=<url-encoded query>&category=<category>&limit=5

必ず category を指定して検索を始めてください。 カテゴリを指定しない検索では SDK リファレンスページが大半を占めます（socket mode や oauth のようなクエリでは、検索結果の上位 10 件がすべて Bolt／Node のページになることがあります）。その結果、多くの質問で実際に必要となる概念やリファレンスの内容が埋もれてしまいます。開発者の意図に応じて、最初のカテゴリを選んでください。

• guides — 「～するには？」「～とは？」などの質問や、プラットフォームに関する概念的な質問に対するデフォルトです（Events API、OAuth、Socket Mode、マニフェスト、モーダル、App Home）。迷ったらここから始めます。
• reference — 特定のメソッド、イベント、スコープ、オブジェクト、Block Kit 要素について調べる場合に使います。特に chat.postMessage のような正確な名前がある場合に適しています。
• ツール／SDK カテゴリ（python、javascript、java、slack_cli、slack_github_action、deno_slack_sdk）— 開発者が使っているツールがわかっている場合に限り使用します。ステップ 3を参照してください。

たとえば、概念としての socket mode は、https://docs.slack.dev/api/v1/search?query=socket%20mode&category=guides&limit=5 で検索します。

レスポンスは JSON です。

{
  "total_results": 12,
  "results": [
    { "url": "/apis/events-api/using-socket-mode", "title": "Using Socket Mode" }
  ],
  "limit": 5
}

results を確認し、最適な title／url の一致を探してから、ステップ 2でページを読みます。クエリの指定は必須です。query なしでエンドポイントを呼び出すと、error フィールドを含む 400 が返されます。

カテゴリの一覧：

カテゴリ	結果の範囲
guides	概念的なガイドと操作手順
reference	API リファレンス：メソッド、イベント、スコープ、オブジェクト、Block Kit
changelog	変更履歴とリリースノート
python	Python ツール（Bolt for Python、Python Slack SDK）
javascript	JavaScript ツール（Bolt for JS、Node Slack SDK）
java	Java ツール（Bolt for Java、Java Slack SDK）
slack_cli	Slack CLI のドキュメント
slack_github_action	Slack Send GitHub Action のドキュメント
deno_slack_sdk	Deno Slack SDK のドキュメント

カテゴリを指定した検索で適切な結果が見つからない場合は、検索範囲を広げます。まず、もう一方の可能性が高いカテゴリ（guides ⇄ reference）を試し、それでも見つからなければ最後の手段として category を省略します。認識されない値を指定すると、有効なカテゴリを列挙した error フィールドを含む 400 が返されます。その場合は、有効なカテゴリのいずれかを指定するか、カテゴリを指定せずに再実行してください。

検索で適切な結果が見つからない場合、または 500／一時的なエラーが返される場合の代替手段（このエンドポイントはレート制限されており、キャッシュは約 5 分間有効です）：

• https://docs.slack.dev/llms-sitemap.md を WebFetch します。すべてのドキュメントページの .md URL が一覧になっているため、関連するパスを探します。
• API リファレンスを調べる場合は、情報が充実したインデックスページを使うと、より速く見つかることがあります。https://docs.slack.dev/reference/methods.md、.../events.md、.../scopes.md、.../objects.md、.../block-kit.md には、それぞれすべての項目と簡単な説明、および .md へのリンクが掲載されています。
• 開発者が Slack CLI を利用できる場合は、ターミナルで slack docs search "<query>" を実行すると、同じ検索を行えます（slack:slack-cli スキルを参照）。

---

ステップ 2：ページを読む（Markdown を取得）

ページ参照（ステップ 1 の url、または開発者が貼り付けたリンク）がわかったら、その Markdown を読みます。

1. 参照先を .md URL に正規化します。
   • ステップ 1 のサイト相対パス（例：/apis/events-api/using-socket-mode）の場合：先頭に https://docs.slack.dev を付けます。
   • 開発者が貼り付けた完全な URL の場合：まず #anchor を削除します。
   • .md を追加します。例：…/using-socket-mode → https://docs.slack.dev/apis/events-api/using-socket-mode.md。 サーバーは .md のリクエストを小文字に変換するため、大文字と小文字は区別されません。chat.postMessage.md と chat.postmessage.md はどちらも解決されます。
2. WebFetch します。ページの冒頭には Source: <original-url> があり、その後にページ本文の Markdown が続きます。
3. 取得した内容に基づいて開発者に回答し、Source の URL を引用します。

ページが長く、開発者からの質問が限定的な場合は、ページを取得して、該当するセクションだけを引用してください。ページ全体をそのまま出力しないでください。

---

ステップ 3：ツールと SDK のドキュメント

公式ツールによって実装の詳細は大きく異なるため、まず開発者がどのツールを使用しているかを確認し、そのツールのドキュメントサブツリーに絞って読み進めてください。それぞれのドキュメントは https://docs.slack.dev/tools/<name> の下にあり、ほかのページと同様に .md 形式で取得できます（例：https://docs.slack.dev/tools/bolt-js/concepts.md）。開発者が明言していない場合は、決めつける前に確認してください。

ツール	ドキュメントのパス	検索 category	開発者が次のことを行う場合に使用
Slack CLI	/tools/slack-cli	slack_cli	ターミナルからアプリをスキャフォールド、実行、または管理する場合、あるいは slack コマンドやアプリマニフェストに言及している場合
Bolt for JavaScript	/tools/bolt-js	javascript	Bolt フレームワークを使って Node/TypeScript でアプリを構築する場合
Bolt for Python	/tools/bolt-python	python	Bolt フレームワークを使って Python でアプリを構築する場合
Bolt for Java	/tools/java-slack-sdk	java	Bolt を使って Java でアプリを構築する場合（Bolt for Java のドキュメントは Java SDK に含まれています）
Node Slack SDK	/tools/node-slack-sdk	javascript	Bolt フレームワーク全体は使わず、低レベルの Node クライアント（@slack/web-api、@slack/socket-mode）を使う場合
Python Slack SDK	/tools/python-slack-sdk	python	Bolt を使わず、低レベルの Python クライアントを使う場合
Java Slack SDK	/tools/java-slack-sdk	java	Java クライアントを使う場合、または Bolt for Java を使用している場合
Slack Send GitHub Action	/tools/slack-github-action	slack_github_action	GitHub Actions のワークフローから Slack にデータを送信する場合

使用するツールが分かったら、ステップ 1 の該当する category を指定して検索対象を絞り込んでください。例：…?query=middleware&category=javascript。言語ごとのグループに注意してください。Bolt for JavaScript と Node Slack SDK はどちらも javascript に属します（同様に python と java も、それぞれ Bolt フレームワークと低レベル SDK の両方を対象とします）。つまり、category で絞り込まれるのは単一のサブツリーではなく、言語ファミリーです。

Bolt は、対応する言語の SDK を基盤とするフレームワークです。トピックがどのサブツリーにあるか分からない場合は、検索 API（ステップ 1）に戻ってください。これらすべてがインデックスされています。