agentleFS
DingyangLyuDingyangLyu/MatClaw/.claude/skills/add-slack/SKILL.md

add-slack

Skill98 starsChanged 8 months agoApache-2.0View on GitHub

Add Slack as a channel. Can replace WhatsApp entirely or run alongside it. Uses Socket Mode (no public URL needed).

  • Reads credentials

10 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use add-anydoc, add-clidash and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • TomGranotSkill

    add-anydoc

    Add local office-document-to-Markdown conversion to NanoClaw agent containers with the pinned Firecrawl AnyDoc CLI. Use when agents need to read attached Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, or text-based PDF files without uploading them to a hosted parser.

    Also in 5 projects that use this

  • TomGranotSkill

    add-clidash

    Add clidash — a zero-dependency, read-only web dashboard that derives its tabs and tables at runtime from any CLI that lists resources as JSON. Ships pre-wired for NanoClaw's ncl CLI (agent groups, sessions, channels, users, roles), plus message-activity charts, a log tail, and a read-only file viewer for group skills/CLAUDE.md/profiles.

    Also in 5 projects that use this

  • b1rdmaniaSkill

    migrate-memory

    Migrate from monolith CLAUDE.md to the three-file memory system (identity + state + log). Non-destructive — backs up the original first.

    Also in 7 projects that use this

  • qwibitaiSkill

    add-iron-proxy

    Install or refresh Iron Proxy and its official Iron Control web console for NanoClaw. Use when selecting the Iron gateway, adding its management UI, configuring credentials and grants, or restoring the proxy, approval bridge, and agent guidance.

    Also in 4 projects that use this

  • qwibitaiSkill

    add-mattermost

    Add a self-hosted or cloud Mattermost bot channel through the Chat SDK bridge, reusing a healthy server when available and linking to official server setup guidance when needed.

    Also in 4 projects that use this

  • nanocoaiSkill

    add-cursor

    Use Cursor (local Agent SDK) as a full agent provider — planning, tool orchestration, MCP tools, session resume — alongside or instead of Claude. Cursor-account sign-in or API key, held by the credential gateway. Per-group via `ncl groups config update --provider cursor`. Distinct from using Cursor as a cloud agent (those run on Cursor VMs and are not this provider).

    Also in 3 projects that use this

  • +5 more from TomGranot
  • +1 more from qwibitai

The file

Show its rules and text

We split this skill into the rules it gives an agent

23 rules. 0 are common, 13 are distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 10 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read .matclaw/state.yaml. If slack is in applied_skills, skip to Phase 3 (Setup).

    line 14
  2. Distinctive:

    Do they already have a Slack app configured?: If yes, collect the Bot Token and App Token now.

    line 18
  3. Very specific:

    Run the skills engine to apply this skill's code package.

    line 22
  4. Very specific:

    If .matclaw/ directory doesn't exist yet:

    line 26
  5. Distinctive:

    If the apply reports merge conflicts, read the intent file:

    line 47
  6. Distinctive:

    All tests must pass (including the new slack tests) and build must be clean before proceeding.

    line 57
  7. Very specific:

    If the user doesn't have a Slack app, share SLACK_SETUP.md which has step-by-step instructions with screenshots guidance, troubleshooting, …

    line 63
  8. Distinctive:

    Create a Slack app at api.slack.com/apps

    line 66
  9. Very specific:

    Add OAuth scopes: chat:write, channels:history, groups:history, im:history, channels:read, groups:read, users:read

    line 69
  10. Distinctive:

    Wait for the user to provide both tokens.

    line 72
  11. Distinctive:

    Wait for the user to provide the channel ID.

    line 112
  12. Distinctive:

    Use the IPC register flow or register directly.

    line 116
  13. Very specific:

    Check SLACK_BOT_TOKEN and SLACK_APP_TOKEN are set in .env AND synced to data/env/env

    line 165
  14. Very specific:

    Check channel is registered: sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'slack:%'"

    line 166
  15. Distinctive:

    Verify Socket Mode is enabled in the Slack app settings

    line 172
  16. Very specific:

    Verify the bot is subscribed to the correct events (message.channels, message.groups, message.im)

    line 173
  17. Distinctive:

    Verify the bot has been added to the channel

    line 174
  18. Distinctive:

    Check that the bot has the required OAuth scopes

    line 175
  19. Distinctive:

    Add the bot to each channel you want it to monitor

    line 180
  20. Very specific:

    Check the bot has channels:history and/or groups:history scopes

    line 181
  21. Very specific:

    If the bot logs missing_scope errors:

    line 185
  22. Distinctive:

    Add the missing scope listed in the error message

    line 187
  23. Distinctive:

    If the channel ID is hard to find:

    line 195

“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add Slack Channel

This skill adds Slack support to MatClaw using the skills engine for deterministic code changes, then walks through interactive setup.

Phase 1: Pre-flight

Check if already applied

Read .matclaw/state.yaml. If slack is in applied_skills, skip to Phase 3 (Setup). The code changes are already in place.

Ask the user

Do they already have a Slack app configured? If yes, collect the Bot Token and App Token now. If no, we'll create one in Phase 3.

Phase 2: Apply Code Changes

Run the skills engine to apply this skill's code package. The package files are in this directory alongside this SKILL.md.

Initialize skills system (if needed)

If .matclaw/ directory doesn't exist yet:

npx tsx scripts/apply-skill.ts --init

Or call initSkillsSystem() from skills-engine/migrate.ts.

Apply the skill

npx tsx scripts/apply-skill.ts .claude/skills/add-slack

This deterministically:

  • Adds src/channels/slack.ts (SlackChannel class with self-registration via registerChannel)
  • Adds src/channels/slack.test.ts (46 unit tests)
  • Appends import './slack.js' to the channel barrel file src/channels/index.ts
  • Installs the @slack/bolt npm dependency
  • Records the application in .matclaw/state.yaml

If the apply reports merge conflicts, read the intent file:

  • modify/src/channels/index.ts.intent.md — what changed and invariants

Validate code changes

npm test
npm run build

All tests must pass (including the new slack tests) and build must be clean before proceeding.

Phase 3: Setup

Create Slack App (if needed)

If the user doesn't have a Slack app, share SLACK_SETUP.md which has step-by-step instructions with screenshots guidance, troubleshooting, and a token reference table.

Quick summary of what's needed:

  1. Create a Slack app at api.slack.com/apps
  2. Enable Socket Mode and generate an App-Level Token (xapp-...)
  3. Subscribe to bot events: message.channels, message.groups, message.im
  4. Add OAuth scopes: chat:write, channels:history, groups:history, im:history, channels:read, groups:read, users:read
  5. Install to workspace and copy the Bot Token (xoxb-...)

Wait for the user to provide both tokens.

Configure environment

Add to .env:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token

Channels auto-enable when their credentials are present — no extra configuration needed.

Sync to container environment:

mkdir -p data/env && cp .env data/env/env

The container reads environment from data/env/env, not .env directly.

Build and restart

npm run build
launchctl kickstart -k gui/$(id -u)/com.matclaw

Phase 4: Registration

Get Channel ID

Tell the user:

  1. Add the bot to a Slack channel (right-click channel → View channel details → Integrations → Add apps)
  2. In that channel, the channel ID is in the URL when you open it in a browser: https://app.slack.com/client/T.../C0123456789 — the C... part is the channel ID
  3. Alternatively, right-click the channel name → Copy link — the channel ID is the last path segment

The JID format for MatClaw is: slack:C0123456789

Wait for the user to provide the channel ID.

Register the channel

Use the IPC register flow or register directly. The channel ID, name, and folder name are needed.

For a main channel (responds to all messages):

registerGroup("slack:<channel-id>", {
  name: "<channel-name>",
  folder: "slack_main",
  trigger: `@${ASSISTANT_NAME}`,
  added_at: new Date().toISOString(),
  requiresTrigger: false,
  isMain: true,
});

For additional channels (trigger-only):

registerGroup("slack:<channel-id>", {
  name: "<channel-name>",
  folder: "slack_<channel-name>",
  trigger: `@${ASSISTANT_NAME}`,
  added_at: new Date().toISOString(),
  requiresTrigger: true,
});

Phase 5: Verify

Test the connection

Tell the user:

Send a message in your registered Slack channel:

  • For main channel: Any message works
  • For non-main: @<assistant-name> hello (using the configured trigger word)

The bot should respond within a few seconds.

Check logs if needed

tail -f logs/matclaw.log

Troubleshooting

Bot not responding

  1. Check SLACK_BOT_TOKEN and SLACK_APP_TOKEN are set in .env AND synced to data/env/env
  2. Check channel is registered: sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'slack:%'"
  3. For non-main channels: message must include trigger pattern
  4. Service is running: launchctl list | grep matclaw

Bot connected but not receiving messages

  1. Verify Socket Mode is enabled in the Slack app settings
  2. Verify the bot is subscribed to the correct events (message.channels, message.groups, message.im)
  3. Verify the bot has been added to the channel
  4. Check that the bot has the required OAuth scopes

Bot not seeing messages in channels

By default, bots only see messages in channels they've been explicitly added to. Make sure to:

  1. Add the bot to each channel you want it to monitor
  2. Check the bot has channels:history and/or groups:history scopes

"missing_scope" errors

If the bot logs missing_scope errors:

  1. Go to OAuth & Permissions in your Slack app settings
  2. Add the missing scope listed in the error message
  3. Reinstall the app to your workspace — scope changes require reinstallation
  4. Copy the new Bot Token (it changes on reinstall) and update .env
  5. Sync: mkdir -p data/env && cp .env data/env/env
  6. Restart: launchctl kickstart -k gui/$(id -u)/com.matclaw

Getting channel ID

If the channel ID is hard to find:

  • In Slack desktop: right-click channel → Copy link → extract the C... ID from the URL
  • In Slack web: the URL shows https://app.slack.com/client/TXXXXXXX/C0123456789
  • Via API: curl -s -H "Authorization: Bearer $SLACK_BOT_TOKEN" "https://slack.com/api/conversations.list" | jq '.channels[] | {id, name}'

After Setup

The Slack channel supports:

  • Public channels — Bot must be added to the channel
  • Private channels — Bot must be invited to the channel
  • Direct messages — Users can DM the bot directly
  • Multi-channel — Can run alongside WhatsApp or other channels (auto-enabled by credentials)

Known Limitations

  • Threads are flattened — Threaded replies are delivered to the agent as regular channel messages. The agent sees them but has no awareness they originated in a thread. Responses always go to the channel, not back into the thread. Users in a thread will need to check the main channel for the bot's reply. Full thread-aware routing (respond in-thread) requires pipeline-wide changes: database schema, NewMessage type, Channel.sendMessage interface, and routing logic.
  • No typing indicator — Slack's Bot API does not expose a typing indicator endpoint. The setTyping() method is a no-op. Users won't see "bot is typing..." while the agent works.
  • Message splitting is naive — Long messages are split at a fixed 4000-character boundary, which may break mid-word or mid-sentence. A smarter split (on paragraph or sentence boundaries) would improve readability.
  • No file/image handling — The bot only processes text content. File uploads, images, and rich message blocks are not forwarded to the agent.
  • Channel metadata sync is unbounded — syncChannelMetadata() paginates through all channels the bot is a member of, but has no upper bound or timeout. Workspaces with thousands of channels may experience slow startup.
  • Workspace admin policies not detected — If the Slack workspace restricts bot app installation, the setup will fail at the "Install to Workspace" step with no programmatic detection or guidance. See SLACK_SETUP.md troubleshooting section.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.