feat: adds docs skill by lukegalbraithrussell · Pull Request #55 · slackapi/slack-skills-plugin

lukegalbraithrussell · 2026-06-18T21:04:18Z

This PR adds a docs skill. It answers Slack platform questions from the live docs at docs.slack.dev rather than from memory.

The process

Discover the right page via the docs search API (/api/v1/search), always scoped with a category (guides, reference, etc.) so results aren't swamped by SDK pages.
Fall back to /llms-sitemap.md and the enriched reference index pages when search misses or is rate-limited.
Read any page as clean markdown by appending .md to its URL, and cite the Source: line back to the developer.

If the developer pastes a docs.slack.dev link, it skips discovery and fetches directly (Fast Path). Testing so far feels snappy; the search-first-then-sitemap approach is open to reassessment.

Skill boundaries

This skill overlapped with two existing ones, so this PR draws clear lines:

slack-docs — general "how does X work?" / conceptual questions and reading guide pages (no auth, no CLI needed).
slack-cli — narrowed to terminal-based lookups via slack docs search; its description no longer claims general doc search.
slack-api — Web API method details (scopes, parameters, pagination) still route here.

Verified via the tool-selection eval: a method question correctly routes to slack-api, not slack-docs.

…cp-plugin into feat-docs-skill

WilliamBergamin

Awesome work 💯 this project is starting to take shape 🏗️

It keeps surprising me how much overlap the skills have! The eval test seems to be catching a lot of those potential overlap issues. Figuring out the scope of each skill is starting to become the trickiest part of this project

Left a few comments, I think we are going in the right direction, the main blocker is around the description, when running the evals locally I found this description was conflicting with other skills 😅

WilliamBergamin · 2026-06-19T19:16:09Z

+---
+
+## Step 2: Read the Page (fetch markdown)
+


🤔 slack-cli vs slack-docs overlap

Needs a boundary decision (the skill-slack-cli-socket-mode failure). We previously expected slack-cli for "Search the Slack developer documentation...", but slack-docs is arguably the better pick

slack-cli's own description still claims "searching the Slack developer documentation for any topic (socket mode, the Events API, OAuth, …)", which is now redundant with this skill.

Maybe we should move general doc-search to slack-docs and narrow the slack-cli's description to "search docs from the terminal via slack docs search". Then update the skill-slack-cli-socket-mode scenario's expected_tool to slack-docs.

Narrowed it and updated scenario!

WilliamBergamin · 2026-06-19T19:16:09Z

+The response is JSON:
+
+```json
+{


💡 (Lower priority)

Verified live: a socket mode search actually returns SDK pages (/tools/java-slack-sdk/…, /tools/node-slack-sdk/…) above the events-api guide shown here. 🤔

Claude claims "The example oversells the ranking.", we might need to improve the search endpoint 😅

maybe quick fix is to have it filter to guides - there is a filter param in endpoint

jk i made a filter on site but not on endpoint hmmmm

no longer jk, aded filter to endpoint and then told it to filter to guides

WilliamBergamin · 2026-06-19T19:25:58Z

+
+---
+
+## Fast Path (the developer already has a URL)


💡 (Lower priority) The "drop #anchor, append .md, WebFetch" logic is duplicated here and in Step 2. Consider making Step 2 the single home for path→.md→fetch and having the Fast Path just hand off to it

Goal is to have less to maintain

brilliant. made it so!

WilliamBergamin · 2026-06-19T19:33:16Z

+PROMPT = "How does Socket Mode work in Slack? Point me to the docs."
+
+
+class TestSlackDocs:


Praise 🙏

WilliamBergamin · 2026-06-19T19:33:28Z


 # Skill inventory (single source of truth)
-EXPECTED_SKILLS = ("create-slack-app", "block-kit", "slack-api", "slack-cli")
+EXPECTED_SKILLS = ("create-slack-app", "block-kit", "slack-api", "slack-cli", "slack-docs")


YESSSSSSSSS

Co-authored-by: William Bergamin <william.bergamin.coen@gmail.com>

The docs search endpoint now supports a `category` param. Lead with it in Step 1 rather than treating it as optional: an uncategorized search skews heavily toward SDK reference pages (queries like "socket mode" or "oauth" can return a top 10 that is entirely Bolt/Node pages), burying the conceptual and reference content most questions are about. - Step 1 (discovery): make `category` the default path, with guidance on picking the starting category (guides for conceptual, reference for a named method/event/scope, a tool category once the SDK is known) and how to widen the search when a categorized query misses. - Step 3 (tool/SDK scoping): map each tool to its matching `category` so the agent can scope discovery to a language family. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Make Step 2 the single home for the page-reference → .md → fetch → cite routine, accepting both a site-relative path from search and a full URL the developer pasted. The Fast Path now hands off to Step 2 instead of duplicating the append-.md/WebFetch logic. Less to maintain, and Step 2 now covers the anchor-stripping case that only the Fast Path mentioned before. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

WilliamBergamin

We don't need the TestSlackDocs anymore 🙏

WilliamBergamin · 2026-07-09T19:56:55Z

+PROMPT = "How does Socket Mode work in Slack? Point me to the docs."
+
+
+class TestSlackDocs:


We don't need this test anymore 🙏

changeset-bot · 2026-07-22T20:24:44Z

🦋 Changeset detected

Latest commit: bdb3a84

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
slack	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Route general documentation questions to the slack-docs skill and scope slack-cli's docs search to terminal-based lookups, removing the overlap between the two skill descriptions. Update the tool-selection eval to match the redrawn boundary: the doc-search scenario now expects slack-docs, plus new scenarios for a conceptual docs question, a docs.slack.dev URL fetch, and a slack-cli local-run to guard slack-cli routing. Also remove the orphaned tests/eval/skills/test_slack_docs.py (referenced a nonexistent Ollama harness and never imported) and add the missing code-fence language that was failing rumdl lint. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

lukegalbraithrussell · 2026-07-22T20:40:14Z

+    {
+        "id": "skill-slack-cli-run-local",
+        "prompt": "Run my Slack app locally for development from the terminal",


Added a cli eval since i changed the only one that had it

lukegalbraithrussell · 2026-07-22T20:41:21Z

@WilliamBergamin Addressed your comments/suggestions!

WilliamBergamin

Looking good 🙏 left a few more comments

WilliamBergamin · 2026-07-28T19:48:37Z

 ## Step 3: Searching Documentation (`slack docs search`)

-Search Slack's developer documentation directly from the terminal.
+Search Slack's developer documentation directly from the terminal. This is the CLI-based path to the same docs; for general documentation questions ("how does X work in Slack?", looking up a guide or reference page) prefer the `slack:slack-docs` skill, which searches and reads `docs.slack.dev` without needing the CLI installed. Reach for `slack docs search` when the developer is already working in the terminal and specifically wants a CLI lookup.


I don't think we need this change 🤔 the description of the docs skill should be sufficient

WilliamBergamin · 2026-07-28T19:51:51Z

+
+> **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.


Praise 🙏

WilliamBergamin · 2026-07-28T20:01:05Z

+
+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:


Is there an endpoint or markdown page that lists these categories rather then hard coding them here?

oh hmmmm there isn't. i can work on adding one but for now i think this is okay because they won't really be changing

Co-authored-by: William Bergamin <william.bergamin.coen@gmail.com>

initial draft

9da7b3c

WilliamBergamin self-requested a review June 18, 2026 21:19

Merge branch 'main' into feat-docs-skill

2f63191

mwbrooks self-requested a review June 19, 2026 05:49

WilliamBergamin and others added 3 commits June 19, 2026 13:39

Merge branch 'main' into feat-docs-skill

b3a030b

Merge remote-tracking branch 'origin/main' into feat-docs-skill

d0763f1

Merge branch 'feat-docs-skill' of https://github.com/slackapi/slack-m…

a850efe

…cp-plugin into feat-docs-skill

WilliamBergamin requested changes Jun 19, 2026

View reviewed changes

lukegalbraithrussell and others added 3 commits June 19, 2026 12:46

Apply suggestions from code review

c2ba8d8

Co-authored-by: William Bergamin <william.bergamin.coen@gmail.com>

lukegalbraithrussell requested a review from WilliamBergamin June 24, 2026 19:05

mwbrooks changed the title ~~Feat: adds docs skill~~ feat: adds docs skill Jun 26, 2026

WilliamBergamin added 2 commits June 29, 2026 12:03

Merge branch 'main' into feat-docs-skill

9a876f6

Merge branch 'main' into feat-docs-skill

977d9e0

WilliamBergamin requested a review from a team as a code owner July 2, 2026 20:03

Merge branch 'main' into feat-docs-skill

085d543

WilliamBergamin reviewed Jul 9, 2026

View reviewed changes

Merge branch 'main' into feat-docs-skill

6c482aa

lukegalbraithrussell commented Jul 22, 2026

View reviewed changes

lukegalbraithrussell requested a review from WilliamBergamin July 22, 2026 20:41

WilliamBergamin requested changes Jul 28, 2026

View reviewed changes

Apply suggestions from code review

4bdc769

Co-authored-by: William Bergamin <william.bergamin.coen@gmail.com>

lukegalbraithrussell commented Jul 28, 2026

View reviewed changes

Comment thread skills/slack-cli/SKILL.md Outdated

Apply suggestion from @lukegalbraithrussell

bdb3a84

lukegalbraithrussell requested a review from WilliamBergamin July 28, 2026 20:05

		PROMPT = "How does Socket Mode work in Slack? Point me to the docs."


		class TestSlackDocs:


		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:

Uh oh!

Conversation

lukegalbraithrussell commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The process

Skill boundaries

Uh oh!

WilliamBergamin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WilliamBergamin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

changeset-bot Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukegalbraithrussell commented Jul 22, 2026

Uh oh!

WilliamBergamin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lukegalbraithrussell commented Jun 18, 2026 •

edited

Loading

changeset-bot Bot commented Jul 22, 2026 •

edited

Loading