Slack Plugin

This plugin integrates Slack with Ai tools, providing tools to search, read, and send messages in Slack. It also offers useful skills for users and developers.

Commands

• /slack:summarize-channel <channel-name>: Summarize recent activity in a Slack channel
• /slack:find-discussions <topic>: Find discussions about a specific topic across Slack channels
• /slack:draft-announcement <topic>: Draft a well-formatted Slack announcement and save it as a draft
• /slack:standup: Generate a standup update based on your recent Slack activity
• /slack:channel-digest <channel1, channel2, ...>: Get a digest of recent activity across multiple Slack channels

Development Commands

Requires Python 3.15+. Run make install before first use to set up the virtual environment and test dependencies.

Always use the make targets rather than invoking python, pytest, ruff, or other tools directly. The targets manage the virtualenv for you; running the underlying tools by hand skips that setup and will behave differently. If a make command is broken or missing something you need, fix the Makefile rather than working around it with the raw command.

Run make help for the full list of targets and what each does. The common ones:

See the maintainers guide for local development and testing setup.

Eval tests (make test-eval) need a Gemini API key and, for the MCP tool-selection test, SLACK_MCP_TOKEN. Copy .env.example to .env and fill in values; each variable is documented inline there, and the Makefile auto-loads .env.

Cross-Skill References

When one SKILL.md references another skill (e.g., to delegate a step instead of duplicating content), follow these rules:

• Use the backticked skill name followed by "skill", e.g. "the slack-cli skill". Don't add the slack: plugin prefix: only Claude Code registers it, and agents that install with npx skills see the bare name.
• When pointing at a specific step, include the step's heading text, not just the number, so references survive future reordering.
• Add a sentence of prose explaining what the referenced section does and why you're delegating to it.
• Don't use markdown anchor links ([text](#step-1)), @-include syntax (@path/to/SKILL.md), or bare file paths: none are idiomatic in installed skills, and @-includes force-load context.

See skills/create-slack-app/SKILL.md Step 1a for an example.

Skill descriptions

A skill's description frontmatter is the only signal an agent uses to decide whether to load the skill. When adding or editing a skill, follow the repo's description conventions: lead with the trigger ("Use when …"), write impersonally, and pack in Slack-specific keywords. The full standard lives in the maintainers guide. For general skill-authoring mechanics, invoke the superpowers:writing-skills skill.

Testing

Two test layers validate skills:

1. Unit (tests/unit/): validates frontmatter fields, naming, and markdown structure. Fast, runs in CI on every PR.
2. Eval (tests/eval/): LLM-judged tests that use a Gemini model. tests/eval/test_tool_selection.py asks the model to pick the expected tool/skill for each of a set of prompts. Because Gemini's free tier caps at 15 requests/minute, the test sleeps ~5s between scenarios (see its teardown_method) to stay under the limit.

To add an eval scenario, append a Scenario (prompt + expected tool) to SCENARIOS in tests/eval/test_tool_selection.py.

CI

GitHub Actions (.github/workflows/ci-build.yml) gates every PR with:

• Lint: make lint
• Typecheck: make typecheck
• Test: make test-unit
• Eval: make test-eval

The eval job reads the GEMINI_API_KEY_* (e.g. GEMINI_API_KEY_BOB, GEMINI_API_KEY_MIC) and SLACK_MCP_TOKEN repository secrets; it skips on PRs from forks, which don't receive secrets. The workflow also runs nightly on a schedule, and a notifications job posts to Slack (via SLACK_REGRESSION_FAILURES_WEBHOOK_URL) when a job fails on main.

Public documentation

docs/ is published to docs.slack.dev. The slackapi/docs repo syncs this directory from main (see its sources.json), so editing docs/slack-skills-plugin.md here is the whole job: there is no second PR to open, and the change goes live when it merges.

public/ is published to docs.slack.dev as-is, not rendered into a page. A file's path under public/ is its URL, so public/agent-setup/prompt.md is served at https://docs.slack.dev/agent-setup/prompt.md. Every file in a mapped folder is published, so keep notes about these files here rather than in a README beside them. Each folder under public/ needs its own entry in the docs repo's sources.json (for example public/agent-setup to static/agent-setup), so adding a folder means a docs PR as well.

public/agent-setup/prompt.md is the setup prompt developers paste into a coding agent: it installs this plugin, then runs create-slack-app. Its install commands must match the Installation section of README.md, which tests/unit/test_agent_setup_prompt.py checks. Change both together. The docs site compiles it as MDX, so write links as [text](url), not <url>.

Any change to what a public developer can see or do must update docs/ in the same PR. Treat it like the changeset, not a follow-up. That includes:

• A new install path, or a change to an existing install command
• Adding, removing, or renaming a skill, which also means the skills table
• A capability that differs by surface (Claude Code, Cursor, Codex): say so explicitly rather than leaving a developer to infer it
• Anything that makes an existing statement on the page wrong, including the list of supported tools

README.md covers the same ground for people arriving via GitHub, so the same PR usually needs the matching edit there. Check both.

Releasing

Releases are automated and run in CI: you never run a release yourself. Your only release-related task is adding a changeset when a PR makes a user-facing change.

See the maintainers guide for the format.

Everything after that is handled by changesets and scripts/changeset_version.sh: merging to main opens a "chore: release" PR, and merging that PR publishes the release.