How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/slackapi/slack-skills-plugin --skill slack-docsBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Slack Platform Documentation
Help the developer find the right page on the official Slack documentation site (https://docs.slack.dev) and read it as clean markdown, so answers come from the live docs rather than memory. The site exposes three machine-readable surfaces an agent can use directly, with no authentication and no Slack workspace:
- A search API method:
GET https://docs.slack.dev/api/v1/search?query=<q>&category=<c>&pin=falsereturns ranked page hits as JSON. Scope every search with acategory(guides, reference, a specific SDK, etc.); an uncategorized search skews heavily toward SDK pages. Always passpin=false, which stops the API from putting this plugin's own page first for searches about coding agents; you already have the plugin. - Per-page markdown: every page is available at its URL + `.md` (e.g.
/quickstart.md). - Index files:
/llms.txt(a curated overview) and/llms-sitemap.md(a list of every markdown page).
If $0 is provided, it is either a docs.slack.dev URL (jump to the Fast Path) or a topic to search (start at Step 1). For a broad "how do I build X on Slack?" question rather than one specific page, read https://docs.slack.dev/llms.txt first; it is a curated, LLM-oriented overview of the platform and the recommended build path.
Critical rules: - The docs are the source of truth. Do not answer a factual question about the Slack platform from memory; discover the page, fetch it, then answer from what it says. - Prefer the `.md` version of any page over the HTML version. It is cleaner for reading and quoting. - Every fetched markdown page begins with a Source: <url> line. Keep that URL so you can cite the page back to the developer.DO NOT rules: - DO NOT invent documentation URLs. Get them from the search API, the sitemap, or a link the developer gave you then verify by fetching. - DO NOT paraphrase a page you have not actually fetched. If a fetch fails, say so rather than filling the gap from memory. - DO NOT assume every URL has a .md version. If a fetch returns an error, fall back to the search API or the sitemap (Step 1) rather than guessing another URL.Fast Path (the developer already has a URL)
If the developer pasted a https://docs.slack.dev/... link, skip discovery and go straight to Step 2 to fetch and read it.
Step 1: Discover the Page (search)
If the Slack CLI is installed, search from the terminal. Load the slack-cli skill (with your skill tool, if you have one) and follow 1a and 1b of its Step 1: Detect the Slack CLI to check whether the public CLI is installed and resolve its command (SLACK_CMD). Don't check for the CLI yourself first: a slack on PATH isn't always the public CLI, and that step tells them apart. Stop there: don't ask the developer about an alias or offer to install the CLI just to search the docs. If neither finds it, use the search API below.
SLACK_CMD docs search '<query>' --category=<category> --limit=5 --hide-pinnedKeep the query in single quotes, so the shell doesn't run anything inside it, and leave any ' out of the query (whats socket mode). Search ignores punctuation. It calls the same search API and takes the same categories as below. On a current CLI, each result links to the page's .md version, ready for Step 2. An older CLI returns the page URL, which Step 2 turns into its .md version. --hide-pinned leaves out the Slack MCP and Skills Plugin page that the API pins to the top of searches about coding agents. You already have the plugin.
Check SLACK_CMD docs search --help first. If search or its --category flag is missing, use the search API below. If only --hide-pinned is missing, the CLI is older than this skill: search without it and skip the plugin page (https://docs.slack.dev/ai/slack-skills-plugin/) if it comes first. Suggest SLACK_CMD upgrade once, as the slack-cli skill's Step 2: Command Discovery via Help does for a missing command or flag.
Otherwise, use the search API. WebFetch this URL, with the query URL-encoded and a category to scope the results:
https://docs.slack.dev/api/v1/search?query=<url-encoded query>&category=<category>&limit=5&pin=falseAlways start with a `category`. An uncategorized search is dominated by SDK reference pages (a query like socket mode or oauth can return a top 10 that is entirely Bolt/Node pages), which buries the conceptual and reference content most questions are actually about. Pick the starting category from the developer's intent:
- `guides` — the default for "how do I…", "what is…", and conceptual platform questions (Events API, OAuth, Socket Mode, manifests, modals, App Home). Start here when in doubt.
- `reference` — for a specific method, event, scope, object, or Block Kit element, especially an exact name like
chat.postMessage. - A tool/SDK category (
python,javascript,java,slack_cli,slack_github_action,deno_slack_sdk) — only once you know the developer's tool. See Step 3.
So socket mode as a concept → https://docs.slack.dev/api/v1/search?query=socket%20mode&category=guides&limit=5&pin=false.
The response is JSON:
{
"total_results": 12,
"results": [
{ "url": "/apis/events-api/using-socket-mode", "title": "Using Socket Mode" }
],
"limit": 5
}Scan results for the best title/url match, then read it in Step 2. A query is required; calling the endpoint with no query returns a 400 with an error field.
Full set of categories:
| Category | Scopes results to |
|---|---|
guides | Conceptual and how-to guides |
reference | API reference: methods, events, scopes, objects, Block Kit |
changelog | Changelog and release notes |
python | Python tools (Bolt for Python, Python Slack SDK) |
javascript | JavaScript tools (Bolt for JS, Node Slack SDK) |
java | Java tools (Bolt for Java, Java Slack SDK) |
slack_cli | Slack CLI docs |
slack_github_action | Slack Send GitHub Action docs |
deno_slack_sdk | Deno Slack SDK docs |
If a categorized search returns no good hit, widen it: try the other likely category (guides ⇄ reference), then drop category entirely as a last resort. An unrecognized value returns a 400 with an error field listing the valid categories, so re-run with one of those or with no category.
Fallbacks when search does not surface a good hit, or returns a 500/temporary error (the endpoint is rate-limited and cached ~5 minutes):
- WebFetch
https://docs.slack.dev/llms-sitemap.md, a flat list of every documentation page's.mdURL, and scan it for the relevant path. - For API reference lookups, the enriched index pages are often faster:
https://docs.slack.dev/reference/methods.md,.../events.md,.../scopes.md,.../objects.md, and.../block-kit.mdeach list every item with a one-line description and a.mdlink.
Step 2: Read the Page (fetch markdown)
Given a page reference (a url from Step 1, or a link the developer pasted), read its markdown.
If the Slack CLI is installed, print the page from the terminal. Use the SLACK_CMD from Step 1. When you came here from the Fast Path with a pasted link, resolve it the same way first, with 1a and 1b of the slack-cli skill's Step 1: Detect the Slack CLI.
SLACK_CMD docs get '<url or path>'It accepts a link from SLACK_CMD docs search, a pasted docs.slack.dev URL, or a site path, with or without .md or an #anchor, and prints the page's markdown. If SLACK_CMD docs --help doesn't list get, the CLI is older than this skill: suggest SLACK_CMD upgrade once and fetch the page as below.
Generated SDK reference pages end in .html and have no markdown version, so docs get reports that and appending .md fails too. WebFetch a .html link as it is.
Otherwise, fetch the markdown:
- Normalize the reference to its
.mdURL:
- A site-relative path from Step 1 (e.g.
/apis/events-api/using-socket-mode): prependhttps://docs.slack.dev. - A full URL the developer pasted, or a link from
SLACK_CMD docs search: drop any#anchorfirst. - Unless it already ends in
.md, drop a trailing/, then append.md, e.g.…/using-socket-mode/→https://docs.slack.dev/apis/events-api/using-socket-mode.md. Keeping the slash (…/using-socket-mode/.md) returns a 404.
The server lowercases .md requests, so casing does not matter: chat.postMessage.md and chat.postmessage.md both resolve.
- WebFetch it. The page opens with
Source: <original-url>; the rest is the page body in markdown. - Answer the developer from the fetched content, and cite the
SourceURL.
If a page is long and the developer asked something narrow, fetch it and quote only the relevant section rather than dumping the whole page.
Step 3: Tool and SDK Documentation
Implementation details differ significantly between the official tools, so establish which one the developer is using first, then scope your reading to that tool's doc subtree. Each lives under https://docs.slack.dev/tools/<name> and its pages are fetchable as .md like any other (e.g. https://docs.slack.dev/tools/bolt-js/concepts.md). If the developer has not said, ask before assuming.
| Tool | Docs path | Search category | Use when the developer… |
|---|---|---|---|
| Slack CLI | /tools/slack-cli | slack_cli | scaffolds, runs, or manages an app from the terminal; mentions slack commands or app manifests |
| Bolt for JavaScript | /tools/bolt-js | javascript | builds an app in Node/TypeScript with the Bolt framework |
| Bolt for Python | /tools/bolt-python | python | builds an app in Python with the Bolt framework |
| Bolt for Java | /tools/java-slack-sdk | java | builds an app in Java with Bolt (Bolt for Java lives in the Java SDK docs) |
| Node Slack SDK | /tools/node-slack-sdk | javascript | wants lower-level Node clients (@slack/web-api, @slack/socket-mode) without the full Bolt framework |
| Python Slack SDK | /tools/python-slack-sdk | python | wants the lower-level Python client without Bolt |
| Java Slack SDK | /tools/java-slack-sdk | java | wants Java clients, or is using Bolt for Java |
| Slack Send GitHub Action | /tools/slack-github-action | slack_github_action | sends data to Slack from a GitHub Actions workflow |
Once you know the tool, narrow discovery with the matching category from Step 1, e.g. …?query=middleware&category=javascript. Note the languages group: both Bolt for JavaScript and the Node Slack SDK fall under javascript (likewise python and java each cover their Bolt framework plus lower-level SDK), so the category scopes to the language family, not a single subtree.
Bolt is the framework built upon the matching language SDK. When unsure which subtree a topic lives in, fall back to the search API (Step 1) as it indexes all of these.