agent-slack 實戰手冊|Slack automation CLI for AI agents

01工具定位

AI agent 的 Slack 操作入口

agent-slack 是一個 Slack CLI,目標讀者是 AI agent 與使用 agent 的工程團隊。README 將它定義為 TypeScript + Bun 寫成的 Slack automation CLI,並列出讀取訊息、瀏覽頻道歷史、搜尋訊息與檔案、下載附件、寫入訊息、管理 channel、讀取 Canvas 等能力。

工具的預設介面是 agent-slack ...。repo 同時提供 skills/agent-slack/,可安裝到 Claude Code、Codex、Cursor 等支援 agent skill 的環境,讓 agent 直接載入命令地圖、target 規則與輸出格式。

輸出固定為 JSON,空值會被修剪,附件會下載成 agent 可讀的本機路徑。這讓 agent 可以先讀取 Slack context,再用 message draft 建立人工可確認的回覆。

Auth
Read
Search
Draft
Explicit Action
JSON Output

Slack automation CLI for AI agents

— stablyai/agent-slack README

02CLI 與 Skill

二段式安裝 CLI 與 agent skill

先安裝 agent-slack CLI,再把 skills/agent-slack/ 安裝到你的 agent 環境。README 提供 Bun 安裝、npm global install 與 Nix flake 三種 CLI 入口;package metadata 標示 Node engine 為 >=22.5。

# Bun installer, README recommended path
curl -fsSL https://raw.githubusercontent.com/stablyai/agent-slack/main/install.sh | sh

# npm global install, Node >= 22.5
npm i -g agent-slack

# Nix flake
nix run github:stablyai/agent-slack

Agent skill 安裝

repo 內建的 skill 是 agent 使用說明書。使用 skills.sh 安裝時,命令會指向 GitHub repo;手動安裝時,從 clone 後的 repo 執行腳本。

# Recommended by README
npx skills add stablyai/agent-slack

# Manual installation from a local clone
bash ./scripts/install-skill.sh

驗證 Slack credentials

macOS 與 Windows 預設讀取 Slack Desktop local data。失敗時,macOS 可改用 Brave、Chrome 或 Firefox 匯入;也可設定 Slack token 與 cookie 環境變數。

agent-slack auth whoami
agent-slack auth import-desktop
agent-slack auth import-brave
agent-slack auth import-chrome
agent-slack auth import-firefox
agent-slack auth test

# Alternative browser token path
export SLACK_TOKEN="xoxc-..."
export SLACK_COOKIE_D="xoxd-..."
agent-slack auth test

# Standard Slack token path
export SLACK_TOKEN="xoxb-..."
agent-slack auth test

03Command Map

Slack 操作的命令地圖

README 的 high-level command map 將 Slack 工作分成 auth、message、channel、user、search、workflow、canvas 等群組。skill 版本再補上 safety 規則:讀取與搜尋可自由執行;送出、編輯、刪除、反應、邀請、建立 channel、mark read、排程、上傳與取消排程都需要明確指示。

Auth · 01

auth whoami / test / import-*

Credential 驗證

列出已設定 workspace 與 token source,測試 Slack credentials,或從 Slack Desktop 與瀏覽器匯入 credentials。

Read · 02

message get <target>

單則訊息

讀取一則 Slack message。threaded message 會回傳 thread metadata,不會直接展開完整 thread 內容。

Read · 03

message list <target>

Thread 與歷史

指定 thread 時列出完整 replies;未指定 thread 時瀏覽近期 channel messages,支援 reaction 與時間區間篩選。

Draft · 04

message draft <target> [text]

人工確認的草稿

開啟 Slack-like browser editor,支援粗體、斜體、刪除線、連結、清單、引用、inline code 與 code block。

Write · 05

message send / edit / delete / react

明確授權的寫入

送出、回覆、編輯、刪除與 reaction。message send 支援附件、Block Kit、thread broadcast 與排程。

Schedule · 06

message scheduled list / cancel

排程佇列

列出 Slack server-side scheduled message queue,並可在訊息送出前取消指定 scheduled message。

Search · 07

search all / messages / files

訊息與檔案搜尋

搜尋 Slack messages 與 files,支援 workspace、channel、user、日期、content type、limit 與 content length 控制。

Artifacts · 08

message files[] / search files

附件下載

訊息與搜尋結果中的 snippets、images、attachments 會下載成本機檔案,並在 JSON 中回傳絕對路徑。

Channels · 09

channel list / new / invite / mark

Channel 管理

列出 conversations、建立公開或私有 channel、邀請內部或 Slack Connect 使用者,並可 mark channel / DM as read。

Users · 10

user list / get / dm-open

成員與DM

列出 users、以 id 或 handle 查詢單一使用者,並為一到多位使用者開啟 DM 或 group DM channel id。

Workflow · 11

workflow list / preview / get / run

Slack workflow 觸發

列出 channel 內 bookmarked 或 featured workflows,預覽 trigger metadata,讀取 workflow definition,或執行 trigger。

Inbox · 12

unreads / later / canvas get

收件匣與文件

讀取 unreads、管理 Slack Later saved messages,並將 Slack Canvas 取回為 Markdown。

任務與命令對照

任務	建議命令	輸出或結果
讀一則 Slack permalink	`agent-slack message get "SLACK_URL"`	單則 message 與 thread summary
讀完整 thread	`agent-slack message list "SLACK_URL"`	`messages[]` JSON array
瀏覽近期 channel history	`agent-slack message list "general" --limit 20`	近期 messages 與 optional cursor
準備可審查回覆	`agent-slack message draft "SLACK_URL" "text"`	Browser editor 與 Slack permalink
搜尋歷史訊息與檔案	`agent-slack search all "query" --channel "general"`	`messages[]` 與 `files[]`
取回 Slack Canvas	`agent-slack canvas get "CANVAS_URL"`	Markdown content

04Official Rules

讀取、草稿與明確執行

以下規則來自 README 與 bundled references,不是社群經驗整理。它們定義 agent 使用 Slack 時的 target 選擇、payload 控制、寫入邊界與多 workspace 行為。

優先使用 Slack message URL

message get、message list、message send、message edit、message delete、reaction 與 mark read 都接受 Slack permalink。URL target 可攜帶 workspace、channel 與 timestamp context。

來源 · references/targets.md

Channel name 需要 workspace selector

多個 workspace 已設定時,channel name 會產生歧義。使用 --workspace "https://myteam.slack.com"、唯一 substring,或設定 SLACK_WORKSPACE_URL;channel ID 不需要這個參數。

來源 · references/targets.md

`message get` 與 `message list` 的分工

message get 回傳單則 message 與 thread summary。需要完整 thread conversation 時,改用 message list;需要近期 channel history 時,對 channel target 執行 message list。

來源 · README

搜尋優先指定 channel

README 的 search tips 建議加上 --channel。Channel-scoped search 會掃描 history/files 並在本機過濾,可降低跨 workspace 或全域搜尋的模糊性。

來源 · README

限制 body 與 search payload

message get/list 支援 --max-body-chars。Search commands 支援 --max-content-chars 與 --limit,可在 agent context budget 內保留可讀輸出。

來源 · references/commands.md

附件輸出是本機路徑

Message 與 search 結果中的附件會下載到 agent-friendly temp directory。macOS default root 是 ~/.agent-slack/tmp/downloads/;設定 XDG_RUNTIME_DIR 時會改到該 runtime directory 底下。

來源 · README / references/output.md

寫入前使用 `message draft`

Bundled skill 明確要求讀取與搜尋可自由執行,寫入類動作需明確指示。非簡單回覆先用 message draft,讓人類在 browser editor 檢查 formatting 與內容。

來源 · skills/agent-slack/SKILL.md

Workflow run 之前先 preview

workflow preview 讀取 trigger metadata 且無副作用。需要表單欄位與 steps 時用 workflow get;執行 trigger 時才用 workflow run。

來源 · README / references/commands.md

05Worked Example

Incident thread 的讀取與草稿

此例使用 repo 文件中的真實命令語法,但不假設任何 workspace 內資料。流程只執行讀取、搜尋與草稿,符合 bundled skill 對 side effect 的預設邊界。



$ You ›
  請讀這個 Slack incident thread,找出誰在處理 rollback,再幫我草擬一段狀態回覆。


claude: Agent ›
  先確認 credentials 與 workspace。


> agent-slack auth whoami
# { "workspaces": [{ "workspace_url": "https://workspace.slack.com", "source": "slack_desktop" }] }


claude: Agent ›
  先讀 root message。若 thread summary 顯示有 replies,再展開完整 thread。


> agent-slack message get "https://workspace.slack.com/archives/C123/p1770165109628379" --include-reactions --resolve-users
# { "message": { "ts": "...", "text": "...", "user": "U123" }, "thread": { "ts": "...", "length": 6 } }


> agent-slack message list "https://workspace.slack.com/archives/C123/p1770165109628379" --max-body-chars 1200 --resolve-users
# { "messages": [{ "ts": "...", "text": "..." }, { "ts": "...", "text": "..." }] }


claude: Agent ›
  用 channel-scoped search 查相關 rollback 訊息與附件。


> agent-slack search all "deploy rollback" --channel "#alerts-staging" --after 2026-01-01 --limit 5
# { "messages": [{ "ts": "...", "text": "..." }], "files": [{ "name": "report.md", "path": "/Users/.../.agent-slack/tmp/downloads/report.md" }] }


claude: Agent ›
  可確認狀態:rollback owner 是 thread 中被指派的 on-call,附件包含最新 smoke test 摘要。現在開草稿,不直接送出。


> agent-slack message draft "https://workspace.slack.com/archives/C123/p1770165109628379" "我讀完 thread 與最新附件。Rollback 目前由 on-call 接手,下一步是補 smoke test 結果與預估完成時間。"
ok: { "draft": "opened", "target": "thread reply" }


# No send/edit/delete/reaction action was executed.

Prefer message draft.

— skills/agent-slack/SKILL.md

檢查點

通過狀態:credentials 已確認,thread 已讀取,相關 channel search 已執行,附件路徑已回傳,reply draft 已在 browser editor 開啟。未通過狀態:agent 在未取得明確指示時執行 message send、message edit、message delete 或 reaction。

這個模式適合 incident triage、每日 standup 摘要、客戶支援 thread 分析與 release channel 狀態更新。需要送出時,把草稿內容與 target 展示給使用者確認,再執行寫入命令。

06限制與邊界

Slack automation 的操作邊界

警告

**寫入類命令需要明確指示。**Bundled skill 將 send、edit、delete、react、invite、create channels、mark read、schedule、upload、cancel scheduled messages 列為需要使用者明確要求的動作。
Credentials 屬於敏感資料。SLACK_TOKEN、SLACK_COOKIE_D、Slack browser token 與匯入流程輸出不得貼進公開 log、issue、報告或 prompt history。
**Chrome 與 Brave 匯入依賴 Apple Events 設定。**README 指出這兩個瀏覽器預設關閉 Allow JavaScript from Apple Events,且 macOS 第一次執行時會要求輸入密碼。
**Channel name 在多 workspace 下會歧義。**使用 channel name 時傳入 --workspace 或設定 SLACK_WORKSPACE_URL;channel ID target 不需要 workspace selector。
排程訊息受 Slack 限制。--schedule 的時間必須在未來,且需落在 Slack 120-day scheduled-send limit 內。--schedule 與 --schedule-in 互斥。
Block Kit 與附件上傳不可混用。--blocks 可送 raw Block Kit JSON,但 README 標示不能與 --attach 同時使用。
Thread broadcast 有 target 限制。--reply-broadcast 只適用 thread reply,DM target 不支援,且不能與 --attach 同時使用。
Channel list 是分頁結果。channel list 回傳單頁與 optional next_cursor;需要下一頁時傳入 --cursor。--all 與 --user 互斥。
Slack Connect 邀請需要 workspace 權限。--external 對應 Slack Connect external invite,README 標示需要對應 permissions/scopes,且 email targets 才適用。
**Unreads 可能受 Enterprise Grid 限制。**README 標示 unreads 使用 client.counts API,部分 Enterprise Grid workspace 可能回傳 team_is_restricted。

07進階路徑

從 skill 到工作流整合

agent-slack 的長期價值在於可被 agent 重複執行的 Slack runbook。CLI 提供穩定命令,skill 提供安全邊界,reference files 提供 target 與輸出規格。

進階玩法地圖

**1. 建立 credentials 檢查步驟。**Runbook 的第一步固定執行 agent-slack auth whoami 與 agent-slack auth test,並確認 workspace selector。

**2. 安裝 bundled skill。**使用 npx skills add stablyai/agent-slack,讓 agent 讀取 safety、target、output 與 command references。

**3. 固定 target 規則。**工作流優先收 Slack permalink;只有在缺少 URL 時才使用 channel name 或 channel ID。多 workspace 下強制傳入 --workspace。

**4. 將寫入改為草稿優先。**Incident update、standup、客戶支援、release announcement 都先走 message draft;只有明確授權後才送出。

**5. 為 payload 設定預設上限。**在 runbook 中固定 --limit、--max-body-chars 與 --max-content-chars,避免 agent context 被 channel history 填滿。

**6. 本機開發與驗證。**CONTRIBUTING.md 指定 bun install、bun run dev -- --help、bun run build、bun run test、bun run typecheck 與 bun run lint。

最該讀的三份延伸閱讀

① README.md:安裝、auth、命令地圖與使用範例。 ② skills/agent-slack/SKILL.md:agent safety、常用命令與 reference 入口。 ③ references/commands.md、targets.md、output.md:命令、target 與 JSON shape。 ④ CONTRIBUTING.md:本機開發、build、test、typecheck 與 release flow。

CLI on $PATH: agent-slack ...

— skills/agent-slack/SKILL.md

Auth

Read

Search

Draft

Explicit Action

JSON Output