pp-slack

Slack — Printing Press CLI

作成者： @mvanhorn（Matt Van Horn）。 コントリビューター： @ChrisGutierrezNet（Chris G. | AI Automation）、 @cathrynlavery（Cathryn Lavery）。

前提条件：CLI をインストールする

このスキルは slack-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使ってインストールします。バイナリのインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がデフォルトです。

   npx -y @mvanhorn/printing-press-library install slack --cli-only
   

2. 確認します：slack-pp-cli --version
3. このスキルを実行するエージェント／ランタイムで、報告されたインストールディレクトリが $PATH に含まれていることを確認します。

npx でのインストールに失敗する場合（Node がない、オフラインなど）は、Go を直接インストールする方法に切り替えてください（Go 1.26.6 以降が必要です）。この方法では $GOPATH/bin（デフォルトは $HOME/go/bin）にインストールされるため、代わりにそのディレクトリを $PATH に追加してください。

go install github.com/mvanhorn/printing-press-library/library/productivity/slack/cmd/slack-pp-cli@latest

インストール後に --version が「command not found」と表示する場合、ランタイムから $PATH 上のバイナリディレクトリが見えていません。確認に成功するまで、スキルのコマンドを実行しないでください。

Slack では、無料プランの保持期間を過ぎたメッセージは非表示になり、エクスポートには管理者権限が必要です。この CLI は、会話、ユーザー、ファイル、リアクションをローカルの SQLite データベースに同期し、全文検索できるようにします。そのため、archive recall を使えば、Slack 自身が提供できなくなった意思決定も見つけられます。このミラーをもとに、どのエンドポイントからも取得できない情報も算出します。catchup ではまだ対応が必要な項目を、threads stale では未回答のスレッドを、health では活動が低下しているチャンネルを確認できます。

この CLI を使う場面

Slack アプリの開発ではなく、Slack のコンテンツに関する質問で、履歴、集計、または繰り返しのクエリが役立つ場合に、この CLI を使います。過去の意思決定を探す、見逃した内容を要約する、活動中のチャンネルを監査する、不透明な Slack ID をユーザーに対応付ける、といった用途に適しています。また、ボットトークンしか持っていない場合にも適しています。ローカルミラーを使えば、Slack 自身の検索エンドポイントではボットトークンの利用が拒否されるような、検索形式の質問にも答えられます。

使用しない場面

以下の場合は、この CLI を使用しないでください。

• Slack アプリの構築、ひな形の作成、デプロイには使用しないでください。その用途には公式の slackapi/slack-cli を使用します。
• Enterprise Grid の管理には使用しないでください。admin.* メソッドは意図的に対象外となっており、通常のワークスペーストークンでは失敗します。
• リアルタイムのボットやイベントリスナーとして使用しないでください。これはリクエスト／レスポンス型のツールであり、Socket Mode や Events API のランタイムはありません。
• 同期していないワークスペースの読み取りには使用しないでください。アーカイブを利用するすべてのコマンドは、空の結果を黙って返すのではなく、ミラーが未同期であることを報告します。
• コンプライアンスや法的なエクスポートには使用しないでください。その用途には Slack の Discovery API と admin export があり、このツールにはない保証が提供されます。

独自の機能

これらの機能は、この API を扱う他のツールでは利用できません。

Slack より長く保持できるローカルアーカイブ

• archive recall — ローカルアーカイブ内のメッセージを検索します。Slack がすでに90日間の保持期間を過ぎて非表示にしたメッセージも対象です。

  回答に90日より前の情報が含まれる可能性がある場合や、ボットトークンしか持っていない場合は、検索の代わりにこちらを使います。Slack の検索エンドポイントはボットトークンを完全に拒否するためです。

  slack-pp-cli archive recall "deploy" --agent --limit 20
  

• archive coverage — ローカルミラーにチャンネルごとのどの日付範囲のデータが実際に含まれているか、またどこに欠落があるかを表示します。

  空の検索結果を信頼する前に確認し、実際に該当データがないのか、未同期の範囲があるのかを判断します。

  slack-pp-cli archive coverage --json
  

量よりも対応すべきこと

• catchup — 離れていた間に起きたことを確認します。チャンネルごとの新着メッセージ、自分宛てのメンション、返信を待っているスレッドを確認できます。

  チャンネルの一覧表示、チャンネルごとの履歴取得、メンションの手動確認をまとめて置き換える単一の呼び出しとして使います。

  slack-pp-cli catchup --since 24h --agent
  

• threads stale — アーカイブ全体から、最後の返信が自分以外のもので、その後誰も返信していないスレッドを一覧表示します。

  最近のものではなく、未返信のものを知りたい場合に使います。

  slack-pp-cli threads stale --days 3 --json
  

ワークスペースの管理

• health — 1 日あたりのメッセージ数、投稿者数（重複なし）、初回返信までの時間の中央値、最終稼働からの日数でチャンネルを比較します。

  ワークスペースの管理者ではなく、エクスポート機能や管理コンソールも使えない場合に、アーカイブ候補を判断するために使います。

  slack-pp-cli health --dying --json
  

• users activity — あるユーザーがどこに投稿しているか、どのスレッドで中心的な役割を担っているか、最後に確認されたのはいつかを把握します。

  自分自身ではなく、名前が指定されたチームメイトの引き継ぎや朝会の状況を把握するために使います。

  slack-pp-cli users activity chris --days 30 --json
  

ID の解決

• users whois — 不透明な Slack ID、ハンドル、メールアドレスを、共通チャンネル、タイムゾーン、おやすみモードの状態、最終確認日時を含む 1 つのカードに変換します。

  ペイロードで U または C から始まる ID のみを受け取ったら、識別子ごとに users info を呼び出す代わりに、すぐに使います。

  slack-pp-cli users whois U04AB9XYZ --agent
  

コマンドリファレンス

api-test — API テストを管理します

• slack-pp-cli api-test — API 呼び出しコードを確認します。

auth_api — 認証をテストおよび管理します

• slack-pp-cli auth-api revoke — 現在の認証トークンを失効させます
• slack-pp-cli auth-api test — 認証トークンをテストし、ID 情報を取得します

bots — ボットユーザーの情報を取得します

• slack-pp-cli bots — ボットユーザーの情報を取得します

canvases — Slack キャンバスを作成、編集、共有、削除します

• slack-pp-cli canvases create — 単独、またはチャンネルに紐付けてキャンバスを作成します
• slack-pp-cli canvases read — キャンバスの内容を読み取ります
• slack-pp-cli canvases edit — 既存のキャンバスに変更を適用します
• slack-pp-cli canvases delete — キャンバスを削除します
• slack-pp-cli canvases access-set — ユーザーまたはチャンネルにキャンバスへのアクセス権を付与します
• slack-pp-cli canvases sections — 対象を絞った編集に使うキャンバスのセクション ID を検索します

canvases:write と canvases:read が必要です。また、read には files:read も必要です。read の戻り値は Markdown ではなく HTML です（Slack にはキャンバスの内容を取得するエンドポイントがないため、元ファイルをダウンロードします）。そのため、作成して読み取る手順は元の内容を完全には再現できません。編集対象を指定するには、 キャンバスを読み取り、HTML からセクション ID を取得します。sections は、各 ID が対応する内容を含まずに ID を返します。

chat-delete-scheduled-message — チャットの予約済み削除メッセージを管理します

• slack-pp-cli chat-delete-scheduled-message — キューから保留中の予約済みメッセージを削除します。

chat-me-message — チャットの自分メッセージを管理します

• slack-pp-cli chat-me-message — チャンネルに自分メッセージを投稿します。

chat-post-ephemeral — チャットのエフェメラルメッセージを管理します

• slack-pp-cli chat-post-ephemeral — チャンネル内のユーザーにエフェメラルメッセージを送信します。

chat-unfurl — チャットのリンク展開を管理します

• slack-pp-cli chat-unfurl — ユーザーが投稿した URL に対してカスタムのリンク展開動作を提供します

conversations — チャンネルの履歴の読み取り、チャンネルの一覧表示、チャンネルメンバーシップの管理を行います

• slack-pp-cli conversations archive — チャンネルをアーカイブします
• slack-pp-cli conversations create — 新しいチャンネルを作成します
• slack-pp-cli conversations get — チャンネルの情報を取得します
• slack-pp-cli conversations history — --channel ID でチャンネルの履歴を取得するか、--user USER_ID と SLACK_USER_TOKEN で既存の DM を読み取ります。DM の検索では会話は作成されず、ライブアクセスが必要です。D で始まるチャンネルと --user では --data-source local は拒否されます。
• slack-pp-cli conversations invite — ユーザーをチャンネルに招待します
• slack-pp-cli conversations list — ワークスペース内のすべてのチャンネルを一覧表示します
• slack-pp-cli conversations mark — 特定のメッセージまでチャンネルを既読にします
• slack-pp-cli conversations members — チャンネルのメンバーを一覧表示します
• slack-pp-cli conversations replies — スレッド内の返信を取得します
• slack-pp-cli conversations set-purpose — チャンネルの目的を設定します
• slack-pp-cli conversations set-topic — チャンネルのトピックを設定します
• slack-pp-cli conversations unarchive — チャンネルのアーカイブを解除します

conversations-close — 会話の終了を管理します

• slack-pp-cli conversations-close — ダイレクトメッセージまたは複数人のダイレクトメッセージを終了します。

conversations-join — 会話への参加を管理します

• slack-pp-cli conversations-join — 既存の会話に参加します。

conversations-kick — 会話からの退出を管理します

• slack-pp-cli conversations-kick — ユーザーを会話から削除します。

conversations-leave — 会話からの退出を管理します

• slack-pp-cli conversations-leave — 会話から退出します。

conversations-open — 会話の開始を管理します

• slack-pp-cli conversations-open — ダイレクトメッセージまたは複数人のダイレクトメッセージを開始するか、再開します。

conversations-rename — 会話の名前変更を管理します

• slack-pp-cli conversations-rename — 会話の名前を変更します。

dnd — おやすみモードの設定を管理します

• slack-pp-cli dnd end-dnd — 現在のおやすみモードのセッションをただちに終了します
• slack-pp-cli dnd end-snooze — 現在のおやすみモードのセッションを終了します
• slack-pp-cli dnd get — 認証済みユーザーのおやすみモードの状態を取得します
• slack-pp-cli dnd set-snooze — 指定した分数、おやすみモードを有効にします
• slack-pp-cli dnd team-info — 複数のユーザーのおやすみモードの状態を取得します

emoji — ワークスペース内のカスタム絵文字を一覧表示します

• slack-pp-cli emoji — ワークスペース内のすべてのカスタム絵文字を一覧表示します

files — ファイルをアップロード、一覧表示、管理します

• slack-pp-cli files delete — ファイルを削除します
• slack-pp-cli files get — ファイルの情報を取得します
• slack-pp-cli files list — ワークスペース内のファイルを一覧表示します
• slack-pp-cli files upload — ファイルを Slack にアップロードします。--file <path> を指定するか、インラインテキストには --filename とともに --content を指定します。--channel を指定すると共有され、--thread-ts を指定するとスレッドに追加されます。外部アップロードフローを実行します（旧 files.upload は 廃止されています）。--channels にはチャンネルを 1 つだけ指定できます。

files-comments-delete — ファイルのコメント削除を管理します

• slack-pp-cli files-comments-delete — ファイルに既存のコメントを削除します。

files-remote-add — リモートファイルの追加を管理します

• slack-pp-cli files-remote-add — リモートサービスからファイルを追加します

files-remote-info — リモートファイルの情報取得を管理します

• slack-pp-cli files-remote-info — Slack に追加されたリモートファイルの情報を取得します

files-remote-list — リモートファイルの一覧表示を管理します

• slack-pp-cli files-remote-list — Slack に追加されたリモートファイルの情報を取得します

files-remote-remove — リモートファイルの削除を管理します

• slack-pp-cli files-remote-remove — リモートファイルを削除します。

files-remote-share — リモートファイルの共有を管理します

• slack-pp-cli files-remote-share — リモートファイルをチャンネルに共有します。

files-remote-update — リモートファイルの更新を管理します

• slack-pp-cli files-remote-update — 既存のリモートファイルを更新します。

files-revoke-public-url — ファイルの公開 URL を無効化する操作を管理します

• slack-pp-cli files-revoke-public-url — ファイルの公開／外部共有アクセスを取り消します files-shared-public-url — ファイルの公開 URL 共有を管理

• slack-pp-cli files-shared-public-url — ファイルを公開／外部共有できるようにします。

messages — チャンネルや DM のメッセージを送信、読み取り、更新、削除

• slack-pp-cli messages delete-message — メッセージを削除
• slack-pp-cli messages get-permalink — メッセージのパーマリンク URL を取得
• slack-pp-cli messages list-scheduled — 予約済みメッセージを一覧表示
• slack-pp-cli messages post-message — チャンネル、DM、またはスレッドにメッセージを送信します。以前の post_message 表記もエイリアスとして引き続き使用できます。
• slack-pp-cli messages schedule-message — メッセージの後日の配信を予約
• slack-pp-cli messages update-message — 既存のメッセージを更新

pins — チャンネルのメッセージをピン留め、またはピン留め解除

• slack-pp-cli pins add — チャンネルにメッセージをピン留め
• slack-pp-cli pins list — チャンネルのピン留め項目を一覧表示
• slack-pp-cli pins remove — チャンネルのメッセージのピン留めを解除

reactions — メッセージに絵文字リアクションを追加、または削除

• slack-pp-cli reactions add — メッセージに絵文字リアクションを追加
• slack-pp-cli reactions get — メッセージのリアクションを取得
• slack-pp-cli reactions list — 認証済みユーザーが付けたリアクションを一覧表示
• slack-pp-cli reactions remove — メッセージから絵文字リアクションを削除

reminders — 個人的なリマインダーを作成、管理

• slack-pp-cli reminders add — 新しいリマインダーを作成
• slack-pp-cli reminders complete — リマインダーを完了済みにする
• slack-pp-cli reminders delete — リマインダーを削除
• slack-pp-cli reminders get — リマインダーの情報を取得
• slack-pp-cli reminders list — 認証済みユーザーのすべてのリマインダーを一覧表示

search_api — ワークスペース全体のメッセージやファイルを検索

• slack-pp-cli search-api — クエリに一致するメッセージを検索

stars — メッセージやファイルにスターを付ける、または外す

• slack-pp-cli stars add — メッセージ、ファイル、またはチャンネルにスターを付ける
• slack-pp-cli stars list — スター付き項目を一覧表示
• slack-pp-cli stars remove — 項目からスターを外す

team — ワークスペース情報を取得

• slack-pp-cli team access-logs — ワークスペースのアクセスログを取得（管理者権限が必要）
• slack-pp-cli team billable-info — ワークスペースユーザーの課金情報を取得
• slack-pp-cli team get — ワークスペースに関する情報を取得

team-integration-logs — チームのインテグレーションログを管理

• slack-pp-cli team-integration-logs — 現在のチームのインテグレーションログを取得します。

team-profile-get — チームプロフィールの取得を管理

• slack-pp-cli team-profile-get — チームのプロフィールを取得します。

usergroups — ワークスペースのユーザーグループを管理

• slack-pp-cli usergroups create — 新しいユーザーグループを作成
• slack-pp-cli usergroups list — ワークスペース内のすべてのユーザーグループを一覧表示
• slack-pp-cli usergroups update — 既存のユーザーグループを更新
• slack-pp-cli usergroups users-list — ユーザーグループ内のユーザーを一覧表示
• slack-pp-cli usergroups users-update — ユーザーグループのメンバーを更新

usergroups-disable — ユーザーグループの無効化を管理

• slack-pp-cli usergroups-disable — 既存のユーザーグループを無効化

usergroups-enable — ユーザーグループの有効化を管理

• slack-pp-cli usergroups-enable — ユーザーグループを有効化

users — ワークスペースのユーザーを一覧表示、検索

• slack-pp-cli users get — ユーザーに関する情報を取得
• slack-pp-cli users get-presence — ユーザーのオンライン状態を取得
• slack-pp-cli users list — ワークスペース内のすべてのユーザーを一覧表示
• slack-pp-cli users lookup-by-email — メールアドレスでユーザーを検索
• slack-pp-cli users profile-get — ユーザーのプロフィール情報を取得
• slack-pp-cli users profile-set — ユーザーのプロフィール項目を設定
• slack-pp-cli users set-presence — ユーザーのプレゼンス状態を設定

users-conversations — ユーザーの会話を管理

• slack-pp-cli users-conversations — 呼び出しユーザーがアクセスできる会話を一覧表示します。

users-delete-photo — ユーザーの写真削除を管理

• slack-pp-cli users-delete-photo — ユーザープロフィール写真を削除

users-identity — ユーザーのアイデンティティを管理

• slack-pp-cli users-identity — ユーザーのアイデンティティを取得します。

users-set-active — ユーザーのアクティブ状態設定を管理

• slack-pp-cli users-set-active — ユーザーをアクティブとしてマークします。非推奨であり、機能しません。

users-set-photo — ユーザーの写真設定を管理

• slack-pp-cli users-set-photo — ユーザープロフィール写真を設定します

適切なコマンドの見つけ方

やりたいことは分かっているが、どのコマンドがそれを行うか分からない場合は、CLI に直接尋ねてください：

slack-pp-cli which "<capability in your own words>"

which は、自然言語による機能のクエリを、この CLI の厳選された機能インデックスから最も一致するコマンドに解決します。終了コード 0 は少なくとも 1 件の一致を意味し、終了コード 2 は確信のある一致がないことを意味します。その場合は --help に頼るか、より絞り込んだクエリを使用してください。

レシピ

Slack が忘れてしまった決定を探す

slack-pp-cli archive recall "deploy" --agent --select results.channel,results.user,results.ts,results.text

ローカルミラーを検索し、ペイロードを読む価値のあるフィールドだけに絞り込むため、エージェントがメッセージオブジェクト全体にコンテキストを浪費することがありません。

朝の義務チェック

slack-pp-cli catchup --since 24h --json

チャンネルごとの新着量、あなたに言及したメッセージ、最後の返信があなたではないスレッドを返します。

管理者アクセスなしでアーカイブ候補を見つける

slack-pp-cli health --dying --json

チャンネルをアイドル日数と投稿量でランク付けするので、根拠を示してアーカイブを提案できます。

ペイロードから不透明な ID を解決する

slack-pp-cli users whois U04AB9XYZ --agent

裸の Slack ユーザー ID を、共有チャンネル、タイムゾーン、DND 状態、最終確認日時に 1 回の呼び出しで変換します。

空の結果を信頼する前にミラーを確認する

slack-pp-cli archive coverage --json

チャンネルごとにミラーリングされたタイムスタンプ範囲を表示するので、空の検索結果を不在ではなく同期の欠落として読み取ることができます。

認証のセットアップ

認証はベアラートークンですが、Slack は機能を 2 つのトークンタイプに分割しており、どのスコープ付与もその境界を越えることはありません。ボットトークン（xoxb-、SLACK_BOT_TOKEN として設定）は、会話、ユーザー、ファイル、リアクション、ユーザーグループ、絵文字、チーム、dnd、ボットにアクセスできます。ユーザートークン（xoxp-、SLACK_USER_TOKEN として設定）は、search、stars、reminders ファミリーに必要です。これらのファミリーは、どのスコープを追加してもボットトークンに対して not_allowed_token_type を返します。doctor を実行すると、どのトークンタイプが設定されているか、したがってどのコマンドファミリーに到達できるかを確認できます。また、Slack は Marketplace 外で再配布されるアプリに対して conversations.history と conversations.replies をはるかに厳しいレート制限に移行したことに注意してください。独自のワークスペースで作成してインストールする内部アプリは、元の制限を維持します。

セットアップを確認するには slack-pp-cli doctor を実行してください。

エージェントモード

任意のコマンドに --agent を追加します。これは --json --compact --no-input --no-color --yes に展開されます。

• パイプ可能 — JSON は stdout に、エラーは stderr に出力

• フィルタ可能 — --select はフィールドのサブセットを保持します。ドットパスはネストされた構造に降りていき、配列は要素ごとに走査します。冗長な API でコンテキストを小さく保つために重要です：

  slack-pp-cli bots --bot example-value --agent --select id,name,status
  

• プレビュー可能 — --dry-run は送信せずにリクエストを表示します

• オフライン対応 — 同期/検索コマンドは、利用可能な場合はローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトを一切表示せず、すべての入力はフラグです

• 明示的なリトライ — 既に存在する作成を成功と見なす必要がある場合にのみ --idempotent を使用します

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力をプロベナンスエンベロープでラップします：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を、それがライブかローカルかを知るには .meta.source を解析してください。人間が読める N results (live) のサマリーは、stdout がターミナルであり、かつマシン形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合にのみ stderr に出力されます。パイプされた/エージェントのコンシューマーや明示的な形式の実行では、stdout に純粋な JSON が出力されます。

パスと状態

エージェントは、CLI のパスリゾルバーをランタイム契約の一部として扱う必要があります。

• 1 回の実行には --home <dir> を使用するか、SLACK_HOME=<dir> を設定して、4 種類すべてのパスを 1 つのルート配下に移動します。

• 特定の種類だけを別の場所にする必要がある場合に限り、種類ごとの環境変数 SLACK_CONFIG_DIR、SLACK_DATA_DIR、SLACK_STATE_DIR、SLACK_CACHE_DIR を使用します。

• 解決順序は、種類ごとの環境変数、--home、SLACK_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME）、プラットフォームのデフォルトの順です。

• config には、config.toml やプロファイルなどの設定が含まれます。data には、credentials.toml、data.db、Cookie、認証用サイドカーが含まれます。state には、永続化されたクエリ、ジョブ、teach.log が含まれます。cache には、再生成可能な HTTP／キャッシュファイルが含まれます。

• 保存されたシークレットは、data ディレクトリ内の credentials.toml にあります。既存のレガシーな config.toml 内のシークレットは互換性のために読み込まれ、最初の認証書き込み時に config.toml から削除されます。

• slack-pp-cli doctor --fail-on warn を実行すると、パスと認証情報の保存場所に関する警告を確認できます。agent-context は、解決済みディレクトリを必要とするエージェント向けに、スキーマ v4 の paths ブロックを公開します。

• MCP の場合、移動先は MCP ホストの設定で指定します。MCP バイナリは CLI フラグを引き継ぎません。

  {
    "mcpServers": {
      "slack": {
        "command": "slack-pp-mcp",
        "env": {
          "SLACK_HOME": "/srv/slack"
        }
      }
    }
  }
  

フリートでの優先順位：引き継がれた種類ごとの環境変数は、その種類に対する明示的な --home より優先されます。フリート全体で継続的に使用する設定には SLACK_HOME または種類ごとの環境変数を使い、--home は 1 回の実行にのみ使用します。環境変数の設定を解除しても、移動は元に戻りません。SLACK_HOME を解除する前にファイルを手動で移動してください。そうしないと、doctor は以前のルートに残された認証情報を見つけられません。

自動学習

この CLI には、自動で記録する学習ループが備わっています。CLI が記録処理を行います。すべての実行がローカルに記録され、失敗したフラグの後に修正した再試行を行うと flag_alias 候補が自動的に導出され、プレイブックのないクエリファミリーで teach を実行すると、セッションの記録から playbook_candidate が自動生成されます。あなたの役割は判断だけです。まず recall を実行し、表示された候補に対応し、最終的な回答を teach し、修正を確認したら playbook amend を実行します。失敗を手動で記録する必要はありません。

ステップ 1：探索の前に recall

新しいユーザーの質問に対して list/search/drill コマンドを実行する前に、次を実行します。

slack-pp-cli recall "<user's question>" --agent

応答エンベロープ：

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "slack-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

空ストア時の短絡：ストアに学習内容、プレイブック、候補がまだない場合（recall で何も見つからず、learnings list と learnings candidates の両方が空の場合）、クエリのたびに負荷をかけないよう、このセッションの残りでは recall を省略します。何かを教えた後は、再び recall を先に実行します。

ステップ 2：判断ツリー

次の順で candidates、playbook、notes、results[0]、警告を確認します。

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `slack-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

プレイブックと Notes は、リソースごとのパスとは独立しています。recall の応答には、プレイブックと Results[] のヒットの両方が含まれる場合があります。両方を活用してください。プレイブックは実行する手順を示し、リソースのヒットは特定の手順を省略可能にします。デフォルトでは mismatches を省略し、コールドスタート時の予期しない動作を調査する場合に限り --debug-mismatches を渡します。

候補の判断に関する詳細：learnings confirm <id> は候補を実体化する前に、その完全なペイロードを表示します。表示されたペイロードが、検証済みの動作と一致することを確認してください。learnings reject <id> は導出シグネチャに削除済みの印を付け、同じ候補が再び表示されないようにします。エンベロープには、今対応する価値のある候補だけが少数含まれます。すべての未解決候補は slack-pp-cli learnings candidates で一覧表示できます。

段階的な機能縮退：learnings confirm が不明なコマンドとして扱われる場合は、古いバイナリを操作しています。候補に関する案内は無視し、残りのプロトコルに従ってください。

ステップ 3：warnings を必ず確認する

• low_confidence：confidence<2 の行が存在します。ヒントとして扱い、スキップ対象を見つけたものとはみなさないでください。
• resource_not_in_store：学習内容が指すリソースがローカルストアにありません。マッチ検証器はエンティティを分類できませんでした。直接取得して再評価してください。
• cross_alias_match（結果ごと）：この行は別のエイリアスで学習され、entity_lookups を通じてライブクエリの正規名に一致しました（例：「United States」の想起に「USA」の学習内容が適用される場合）。resource_id を信頼してください。
• similar_shape_different_entity:<canonical>（トップレベル）：構造的に一致する行は存在しますが、その正規エンティティはライブクエリのものとは異なります。コールドスタートとして扱われます。この警告には、ヒントとして競合する正規名が含まれますが、その行は Results に昇格されません。
• ambiguous_alias（トップレベル）：単一のクエリエンティティが複数の正規名に解決されました（例：「Cards」→ Arizona Cardinals + St. Louis Cardinals）。リソースを確定する前に、コンテキストから曖昧さを提示してください。
• candidates_present（トップレベル）：エンベロープに candidates セクションが含まれています。ほかの処理より先に、ステップ 2 の候補分岐に従ってください。
• lookup_refresh_available（トップレベル）：クエリ内のエンティティにまだルックアップ行がありませんが、同期データから取得できる可能性があります。slack-pp-cli sync を実行してエンティティのルックアップを更新してください。
• トップレベルの no_learnings_for_query_family：テーブルに Jaccard の下限値を超える行がありませんでした。完全なコールドスタートです。

ステップ 4：回答を確定した後、必ず teach & を実行する

学習は無条件に行います。ストアでは回答できなかったクエリを解決したら、最終的なリソースの対応付けをバックグラウンドで学習させてください。呼び出し回数のしきい値はなく、学習する「価値」があったかどうかを判断する必要もありません。学習はこのループの要です。プレイブックがないファミリーではプレイブックの合成を開始し、同じ指示対象を持つ言い回しは1つのファミリーにまとめられるため、重複に近い学習内容でストアが分断されることはありません。ユーザー向けの回答を組み立てた後、回答を出力する前に、シェルの & を付けて実行してください。これにより呼び出しはすぐに返ります。

slack-pp-cli teach --query "<user's question>" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

成功時は何も表示されません。エラーは、解決済みの状態ディレクトリ内の teach.log にのみ記録されます。最も具体的なリソースを学習させてください。ユーザーが広範な質問をし、親レコードをたどって具体的な回答を見つけた場合は、親ではなく末端の ID を学習させます。CLI は想起時にシード済みの entity_lookups を使ってエイリアスをまたいで解決するため、あるエイリアス（例：「Niners」）での学習内容は、別のエイリアス（例：「49ers」、「San Francisco」）での今後のクエリにも自動的に適用されます。

PII に関するルール：識別子を取り除いた構造的な質問を学習させてください。学習させるクエリやメモに、氏名、メールアドレス、電話番号、アカウント ID などの個人識別子を決して含めないでください。CLI は学習クエリをスキャンして明らかなメールアドレスや電話番号の形式を検出し、警告しますが、処理はブロックしません。警告に頼らず、学習前に取り除いてください。

ステップ 5：プレイブック — オプションのフラグ、自動合成

セッションにプレイブックが「ふさわしい」かどうかを判断する必要はありません。プレイブックがないファミリーに対して teach を実行すると、セッションのジャーナルから playbook_candidate が自動合成され、次のセッションで確認または却下されます。明示的なプレイブックフラグを付けるのは、そのまま記録する価値のある手順をすでに把握している場合に限ります。CLI では見つからなかった回避策（気付かれずに破棄されるフラグ、未公開のパラメーター、ページネーションの工夫、ペイロードに関する注意点など）が該当します。統合された一度の呼び出し形式を優先してください。リソースに関する学習内容とプレイブックを、同じ teach 呼び出しで記録します。

# Common case: record both the resource learning AND the playbook in one call.
slack-pp-cli teach \
  --query "<user's question>" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
slack-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

プレイブックファイルは steps、entity_slots、expected_tool_calls を含む JSON です。ノートファイルは注意点をそのまま記載した Markdown です。ファイルを扱わない呼び出し元（MCP のみのエージェント）は、同じ内容をインラインで渡します。統合された teach 形式では --playbook-json と --playbook-notes を、teach-playbook では --playbook-json と --notes を使用します。統合された teach 形式では、プレイブックのフラグはオプションです。リソースのみを教える場合は、フラグをすべて省略してください。単独の teach-playbook 形式では、プレイブックとノートのフラグの少なくとも一方を設定する必要があります。両方が空の場合は拒否されます。プレイブックは、構造上のクエリファミリー（エンティティを取り除いたもの）に基づいて管理されます。そのため、あるエンティティ形状のクエリから学習したレシピは、同じ形状を持つほかのすべてのクエリに適用されます。呼び出し時には slots_resolved が、実際のクエリの正規形を割り当てます。

今後の呼び出しでプレイブックが見つかった場合は、それを確かな情報源として扱ってください。slots_resolved による置換を適用して手順を再実行し、すでに手順書に記載されている探索は省略して、どの手順よりも先に notes を読んでください。

ステップ 6：デバッグ応答で修正点を特定した場合は、playbook amend & を実行する

デバッグプロトコルへの応答で、ノートやプレイブックに反映すべき具体的な修正点（回避策、未公開のエンドポイント形式、古いフィールド名、確認されたスキーマの変化、空のペイロードへのフォールバックなど）を特定した場合は、ユーザー向けの応答を出す前に playbook amend を実行してください。teach と同様に、実行後の完了を待たずに進めます。

slack-pp-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

修正する価値があるもの：このセッションで実際に確認した動作で、将来の自分が知っていると役立つものです。修正する価値がある例：

• フラグを気付かれずに破棄したり、順序を誤って処理したりする CLI の仕様に対する回避策。
• 未公開のエンドポイント形式（レスポンスが {meta, results} でラップされている、ペイロードがドキュメントの説明よりもさらに 2 階層深いなど）。
• 確認されたスキーマの変化（フィールド名の変更、シーズン間でのインデックスのずれ、API が返すカテゴリラベルの小文字化など）。

ノートに記載しないもの：

• ユーザーの質問に対する、年やエンティティに固有の回答。これは応答であり、学習内容ではありません。
• プレイブックが実行時にすでに取得するチーム、選手、行ごとのデータ。
• 既存のノートの内容を言い換えた記述。

amend コマンドは、ファミリーの既存のノートにタイムスタンプ付きのマーカー（[amend YYYY-MM-DDTHH:MMZ]: <text>）を追記します。複数の amend は蓄積され、監査履歴を確認できます。ファミリーにプレイブックがまだ存在しない場合、amend はノートのみのプレイブックを作成するため、コールドスタート時の修正も反映されます。

amend ノートにおける PII の取り扱い

将来の Printing Press のバージョンで、playbook amend のノートが共有知識として上流に提供される可能性があります。遡及的な削除を行わずに上流への提供を続けられるよう、ユーザーを特定できる情報を含めないでください。

• 含めてはいけないもの：ユーザーのファイルシステム上のパス、個人用の API キーやトークン、ユーザーのメールアドレス、ユーザーの GitHub ハンドル、単一ユーザーに紐付いた特定のクエリ履歴。
• 含めてもよいもの：エンドポイントの形式、未公開のフィールド名、API の注意点、確認されたスキーマの変化、CLI の仕様に対する回避策、汎用的なページネーションや再試行の方法。

修正点がユーザー固有のコンテキストでのみ意味を持つ場合は、プレイブックの amend ではなく、個人用のノートに記録してください。

ループの測定

slack-pp-cli learnings stats は、ローカルの learn_events テーブルから、再現率、教えた内容の再利用率、プレイブックの解決率、候補の承認／却下数を報告します。分母がない間は率が null になります。すべてこのマシン内に保存されます。この CLI でループに効果があるかを確認するために使用してください。

学習の無効化

• 単一のコマンドで --no-learn を指定すると、recall と teach の書き込み処理の両方が短絡されます。蓄積された学習内容の影響を受けてはならない、決定的なエージェントのフローやテストで使用してください。
• 環境変数に SLACK_NO_LEARN=true を設定すると、パイプラインがグローバルに無効になります。

エージェントからのフィードバック

この CLI について気になる点があったら、あなた（またはエージェント）が記録してください。

slack-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
slack-pp-cli feedback --stdin < notes.txt
slack-pp-cli feedback list --json --limit 10

エントリーは、解決されたデータディレクトリ内の feedback.jsonl にローカル保存されます。SLACK_FEEDBACK_ENDPOINT が設定されており、かつ --send が渡されるか SLACK_FEEDBACK_AUTO_SEND=true が設定されている場合を除き、POST されることはありません。デフォルトではローカルのみです。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で。それが積み重なっていく部分です。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力への出力に加えて（またはその代わりに）、指定されたシンクに送られるため、エージェントはコマンド結果を手作業でパイプ処理せずにルーティングできます。次の 3 つのシンクをサポートしています。

シンク	効果
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	<path> に出力をアトミックに書き込みます（一時ファイル＋リネーム）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

不明なスキームは、サポート対象の一覧を示す構造化エラーを返して拒否されます。Webhook の失敗時はゼロ以外の値を返し、URL と HTTP ステータスを標準エラーに記録します。

名前付きプロファイル

プロファイルは、保存されたフラグ値のセットで、複数回の実行で再利用されます。定期実行または繰り返し実行するエージェントが、実行ごとに異なる入力を受け取りながら、同じ保存済みフラグを再利用する場合に使用してください。

slack-pp-cli profile save briefing --json
slack-pp-cli --profile briefing bots --bot example-value
slack-pp-cli profile list --json
slack-pp-cli profile show briefing
slack-pp-cli profile delete briefing --yes

明示的に指定したフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルトより優先されます。agent-context は、実行時に情報を調べるエージェントがプロファイルを見つけられるよう、available_profiles に利用可能なすべてのプロファイルを一覧表示します。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が誤っています）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → slack-pp-cli --help の出力を表示します
2. install で始まる → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の「前提条件」を参照してください
3. それ以外 → 直接使用（--agent を付けて CLI コマンドとして実行します）

MCP サーバーのインストール

1. MCP サーバーをインストールします。

   go install github.com/mvanhorn/printing-press-library/library/productivity/slack/cmd/slack-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add slack-pp-mcp -- slack-pp-mcp
   

3. 確認します：claude mcp list

直接使用

1. インストール済みか確認します：which slack-pp-cli 見つからない場合は、インストールを案内してください（このスキルの冒頭にある「前提条件」を参照）。
2. ユーザーのクエリに最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します。

   slack-pp-cli <command> [subcommand] [args] --agent
   

4. あいまいな場合は、サブコマンドのヘルプを確認します：slack-pp-cli <command> --help。