在需要定位、读取并正确调用 Slack Web API…

适用于开发者询问 Slack Web API 方法、scope/token、调用测试、分页、限流或调试 missing_scope、invalid_auth、channel_not_found 等错误时。

适用场景

解决思路

1. 若提供了 $0：当它是完整 method.name 时跳到 Step 2 读取契约；当它是 family 名称时到 Step 1 在索引中查找。
2. 调用任何方法前，对照其文档页验证方法名和必需 scopes；不要发明方法名或猜测 scopes，方法名使用 family.method 点号格式。
3. 每个响应都有顶层 ok 布尔值；使用结果前始终检查 ok，当 ok:false 时读取 error 字符串。
4. 方法名、scopes、rate tiers 和参数以实时文档页为唯一依据：https://docs.slack.dev/reference/methods/<method-lowercased>.md；从实时索引发现，从方法自身页面读取契约。
5. 不要假设方法是 GET——许多是 POST；检查文档页。
6. 不要把 bearer token 硬编码到已提交代码中，也不要以明文分享 token。
7. 不要使用已弃用方法 files.upload、dialog.open、rtm.*、oauth.access、search.*、stars.*、reminders.* 而不检查替代方法；已弃用方法自己的文档页会命名取代者，新应用优先使用替代方法。
8. 不要通过递增页码分页——Slack 使用不透明 cursor，见 Step 5。
9. 只读方法（*.list、*.info、*.history、conversations.members、auth.test 等）可直接运行来帮助开发者。
10. 改变状态或破坏性方法（chat.postMessage/update/delete，任何 *.delete/*.remove/*.kick/*.archive，以及所有 admin.*）——准备确切命令，并在运行前与开发者确认。
11. 若开发者已知道方法（命名方法、粘贴 https://slack.com/api/<method> URL 或 docs.slack.dev/reference/methods/<method> 链接，或给出 family.method），跳过发现：到 Step 2 读取契约，再到 Step 4 调用并遵守执行姿态。
12. 若能力已知但方法名未知，将开发者意图映射到 family，再映射到候选方法。
13. 浏览索引：WebFetch 实时方法索引 https://docs.slack.dev/reference/methods.md；它列出每个 Web API 方法的 family.method 记法、一行描述和指向方法文档页的链接；扫描候选后跟随链接进入 Step 2 读取契约（索引只有描述；rate tier、scopes、token type 和 pagination 都在 per-method 页面）。
14. 永远不要发布或调用你未在实时页面见过的方法名。
15. 按关键词搜索文档：若倾向于搜索而非扫描索引，且 Slack CLI 可用，使用 slack:slack-cli skill 的 Step 3: Searching Documentation（slack docs search）在终端查询 Slack 文档；没有 CLI 时改为 WebFetch 索引 https://docs.slack.dev/reference/methods.md 并扫描。
16. 用 WebFetch 获取方法文档页；从索引跟随链接，或构造 URL——路径段全小写并以 .md 结尾：https://docs.slack.dev/reference/methods/<method-lowercased>.md；例如 conversations.members → https://docs.slack.dev/reference/methods/conversations.members.md，chat.postMessage → https://docs.slack.dev/reference/methods/chat.postmessage.md；大小写不确定时跟随索引链接而不是手构 URL。
17. 从方法页提取调用前所需内容：HTTP method（GET/POST）和 endpoint https://slack.com/api/<method>、必需 OAuth scopes、token type（bot xoxb- 还是 user xoxp-）、必填与可选参数及类型、示例请求和响应、错误表（方法特定 code）、rate-limit tier。
18. 调用前提取必需参数和必需 scopes。
19. 查询跨领域概念的一般含义时，使用规范参考：response envelope、POST bodies 和 auth 见 https://docs.slack.dev/apis/web-api.md；pagination 见 https://docs.slack.dev/apis/web-api/pagination.md；rate-limit tiers 见 https://docs.slack.dev/apis/web-api/rate-limits.md。
20. 从 Step 2 契约确认 token 类型——bot token 不能调用 user-only 方法，反之亦然；token 前缀（xoxb-、xoxp-、xapp-）含义见 https://docs.slack.dev/authentication/tokens.md。
21. 记录必需 scopes；若调用稍后失败为 missing_scope，读取响应的 needed 和 provided 字段来定位差距，把 needed scope 加到 app manifest 并重新安装 app。
22. admin.* 方法需要 Enterprise Grid org-level token。
23. 对无需认证的方法 api.test（connectivity）、auth.test（验证你发送的 token）和 blocks.validate，无需准备 token。
24. 需要 token 时选择两种方式之一，Slack CLI 可选：若开发者没有 CLI 且不想安装，走 Path B，不要强制安装。
25. Path A：使用 Slack CLI（若已安装或愿意安装）；CLI 提供已认证会话，登录后无需自己处理 token 即可调用方法。
26. Path A 中，用 slack:slack-cli skill 的 Step 1: Detect the Slack CLI 检查公共 Slack CLI 是否安装并解析命令名；该步骤也会在缺失时提议安装。
27. 解析后，在本技能所有 CLI 命令中使用检测到的命令名，并称为 SLACK_CMD；在所有出现 SLACK_CMD 的地方替换为实际解析出的命令名。
28. Path A 中，用 slack:slack-cli skill 的 Step 5: Authentication（slack auth）检查开发者登录状态，需要时引导他们执行 slack login。
29. Path B：无 CLI 时自带 token；从 Slack app config 的 OAuth & Permissions 页面（https://api.slack.com/apps → 你的 app → OAuth & Permissions → OAuth Tokens）获取确定类型的 token：Bot User OAuth Token（xoxb-…）或 User OAuth Token（xoxp-…）；该页也列出当前 granted scopes，确认 Step 2 的 scopes 存在。
30. Path B 中，用 curl 或 SDK 在 Step 4 发送该 token。
31. 调用前先应用执行姿态：如果方法改变状态（post/update/delete/archive/kick，或任何 admin.*），向开发者展示确切命令并获得 yes 再运行；只读调用可直接运行。
32. 通过 Slack CLI 调用：使用 slack:slack-cli skill 的 Step 4: Calling Web API Methods（slack api），该步骤覆盖 SLACK_CMD api <method> key=value … 语法；传入从 Step 2 方法文档页收集的必需参数。
33. 通过 raw HTTP（curl）调用：开发者想要 raw request 或不用 CLI 时，使用 Bash tool；在 Authorization header 发送 token（Step 3 的 bot 或 user token）。
34. curl 默认使用 form-encoded（大多数方法）：例如 curl -s -X POST 'https://slack.com/api/conversations.list' -H 'Authorization: Bearer xoxb-YOUR-TOKEN' -d 'types=public_channel&limit=200'。
35. curl 对复杂参数（如 blocks、view、attachments、metadata）使用 JSON body：例如 curl -s -X POST 'https://slack.com/api/chat.postMessage' -H 'Authorization: Bearer xoxb-YOUR-TOKEN' -H 'Content-Type: application/json' -d '{"channel":"C0123456789","text":"Hello from the API"}'。
36. 调用前检查方法页期望哪种 content type；使用 form encoding 时，结构化参数作为 JSON 编码字符串值传递（例如 blocks=[...]）。
37. 通过 SDK 调用：在 Bolt 和 Slack SDK 中，每个方法是对应文档页参数表的 client function；JavaScript 使用 await client.chat.postMessage({ channel, text, blocks })，Python 使用 client.chat_postMessage(channel=channel, text=text, blocks=blocks)；注意 JS 点形式 chat.postMessage 与 Python 下划线形式 chat_postMessage。
38. 构造 blocks/view payload 时使用 slack:block-kit skill；本技能把该 payload 当 opaque argument，只聚焦围绕它的方法调用。
39. 处理分页：返回集合的方法使用 cursor pagination，不是页码；方法页说明是否分页，完整列表见 https://docs.slack.dev/apis/web-api/pagination.md 的 Methods supporting cursor-based pagination。
40. 分页步骤 1：用 limit 调用（page size——检查方法最大值）。
41. 分页步骤 2：读取响应中的 response_metadata.next_cursor。
42. 分页步骤 3：如果 next_cursor 非空，用 cursor=<next_cursor> 再次调用。
43. 分页步骤 4：重复直到 next_cursor 返回空。
44. 分页示例第一页：curl -s -X POST 'https://slack.com/api/conversations.history' -H 'Authorization: Bearer xoxb-YOUR-TOKEN' -d 'channel=C0123456789&limit=200'。
45. 分页示例下一页：传递 response_metadata.next_cursor 中的 cursor：curl -s -X POST 'https://slack.com/api/conversations.history' -H 'Authorization: Bearer xoxb-YOUR-TOKEN' -d 'channel=C0123456789&limit=200&cursor=dXNlcjpVMDYxTkZUVDI='。
46. Cursors 是不透明的——绝不构造、解析或重用旧 cursor。
47. 当 ok 为 false 时，根据 error 字符串分支处理。
48. 对于方法特定 code，读取方法文档页的 errors table（Step 2）——它列出该方法返回的每个错误，包括跨领域错误如 not_authed、invalid_auth、missing_scope、channel_not_found、invalid_arguments。
49. 对于 envelope 本身含义（ok、error、warning、response_metadata），见 https://docs.slack.dev/apis/web-api.md 的 Evaluating responses。
50. response_metadata.messages 常能指出 malformed argument。
51. 处理 rate limits：在 HTTP 429 或 error 为 ratelimited 时，遵守 Retry-After 响应头（秒）——等待后重试，不要在 tight loop 中重试。
52. 每个方法的 tier（1–4 或 special）限制每分钟调用次数；tier 表在 https://docs.slack.dev/apis/web-api/rate-limits.md，较新的非 Marketplace 应用在某些方法上面临更严格 caps，因此以方法自己页面的确切数字为准。
53. Slack Lists 方法使用 slackLists.* 前缀——裸 lists.* 名称不存在。
54. 本技能拥有方法层——哪个方法、其契约和围绕它的调用；CLI auth 和 calls 委托给 slack:slack-cli，Block Kit payloads 委托给 slack:block-kit。

适用边界 · 注意事项

• 不适用于非 Slack Web API 的任务，或不需要调用/查询 Slack API 方法时。
• 当任务核心是 Slack CLI 认证机制或 Block Kit payload 构造时，分别使用 slack:slack-cli 或 slack:block-kit，本技能只处理方法层。
• 没有 Slack 应用/token（或针对 admin.* 的 Enterprise Grid org-level token）且无法获取时，无法完成需认证的 API 调用。