Slack Master

This is NOT a user-facing skill. It's a shared resource library referenced by Slack integration skills.

Purpose

Provides shared resources to eliminate duplication across:

• slack-connect

• Meta-skill for Slack workspace operations

• slack-send-message

• Send messages to channels/DMs

• slack-list-channels

• List available channels

• slack-search-messages

• Search message history

• And 29 other operation skills...

Instead of loading this skill, users directly invoke the specific skill they need above.

Architecture: DRY Principle

Problem solved: Slack skills would have duplicated content (setup instructions, API docs, auth flow, error handling).

Solution: Extract shared content into slack-master/references/ and slack-master/scripts/ , then reference from each skill.

Result: Single source of truth, reduced context per skill.

Authentication Model: User OAuth

This integration uses User OAuth (not Bot OAuth) for team-wide deployment:

┌─────────────────────────────────────────────────────────────┐ │ USER OAUTH (Per-User Authentication) │ ├─────────────────────────────────────────────────────────────┤ │ • Each team member authenticates with their own account │ │ • Messages sent appear as the user (not a bot) │ │ • Users only see channels/DMs they have access to │ │ • No cross-user data exposure possible │ │ • Token type: xoxp- (user tokens) │ └─────────────────────────────────────────────────────────────┘

Why User OAuth?

• Messages appear from the actual user, not a bot

• Respects existing channel permissions

• No need for bot installation in every channel

• Each user controls their own access

Shared Resources

All Slack skills reference these resources (progressive disclosure).

references/

setup-guide.md - Complete setup wizard

• Creating a Slack App with User OAuth

• Configuring OAuth scopes

• Getting client ID and secret

• Running the OAuth flow

api-reference.md - Slack API patterns

• Base URL and authentication

• All 32 API endpoints documented

• Request/response examples

• Rate limiting info

error-handling.md - Troubleshooting

• Common errors and solutions

• HTTP error codes

• Token expiration handling

• Scope issues

authentication.md - User OAuth flow

• OAuth 2.0 authorization flow

• Token exchange process

• Token refresh (Slack tokens don't expire normally)

• Per-user token storage

scripts/

Authentication & Configuration

check_slack_config.py - Pre-flight validation

python check_slack_config.py [--json]

Argument Required Default Description

--json

No False Output structured JSON for AI consumption

Exit codes: 0=configured, 1=partial, 2=not configured

When to Use: Run this FIRST before any Slack operation. Use to validate user token is configured, diagnose authentication issues, or check if OAuth setup is needed.

setup_slack.py - Interactive OAuth wizard

python setup_slack.py

No arguments - runs interactively. Guides through OAuth authorization, gets user token, saves to .env .

When to Use: Use when Slack integration needs initial setup, when check_slack_config.py returns exit code 2, or when user needs to re-authenticate.

slack_client.py - Shared API client

from slack_client import get_client client = get_client() result = client.post('chat.postMessage', {'channel': 'C123', 'text': 'Hello'})

Provides:

• Automatic token loading from .env

• Request formatting for Slack API

• Error handling and response parsing

• Rate limit awareness

When to Use: Import this in all Slack operation scripts for consistent API access.

Message Operations

send_message.py - Send message (chat.postMessage)

python send_message.py --channel CHANNEL --text "Message" [--thread-ts TS] [--json]

update_message.py - Update message (chat.update)

python update_message.py --channel CHANNEL --ts TIMESTAMP --text "New text" [--json]

delete_message.py - Delete message (chat.delete)

python delete_message.py --channel CHANNEL --ts TIMESTAMP [--json]

schedule_message.py - Schedule message (chat.scheduleMessage)

python schedule_message.py --channel CHANNEL --text "Message" --post-at UNIX_TS [--json]

Channel Operations

list_channels.py - List channels (conversations.list)

python list_channels.py [--types public,private] [--limit N] [--json]

channel_info.py - Get channel info (conversations.info)

python channel_info.py --channel CHANNEL [--json]

channel_history.py - Get messages (conversations.history)

python channel_history.py --channel CHANNEL [--limit N] [--oldest TS] [--latest TS] [--json]

create_channel.py - Create channel (conversations.create)

python create_channel.py --name NAME [--is-private] [--json]

User Operations

list_users.py - List workspace users (users.list)

python list_users.py [--limit N] [--json]

user_info.py - Get user info (users.info)

python user_info.py --user USER_ID [--json]

File Operations

upload_file.py - Upload file (files.upload)

python upload_file.py --file PATH --channels C1,C2 [--title TITLE] [--json]

list_files.py - List files (files.list)

python list_files.py [--channel CHANNEL] [--user USER] [--limit N] [--json]

Search Operations

search_messages.py - Search messages (search.messages)

python search_messages.py --query "search terms" [--count N] [--json]

search_files.py - Search files (search.files)

python search_files.py --query "search terms" [--count N] [--json]

Intelligent Error Detection Flow

When a Slack skill fails due to missing configuration, the AI should:

Step 1: Run Config Check with JSON Output

python 00-system/skills/slack/slack-master/scripts/check_slack_config.py --json

Step 2: Parse the ai_action Field

The JSON output includes an ai_action field that tells the AI what to do:

ai_action What to Do

proceed_with_operation

Config OK, continue with the original operation

run_oauth_setup

Run: python setup_slack.py to authorize

check_scopes

Token exists but missing required scopes

token_revoked

User revoked access, need to re-authorize

Step 3: Help User Fix Issues

If ai_action is run_oauth_setup :

• Tell user: "Slack integration needs setup. Let's authorize your account."

• Run: python 00-system/skills/slack/slack-master/scripts/setup_slack.py

• User will be guided through OAuth flow

• Token saved to .env

• Re-run config check to verify

JSON Output Structure

{ "status": "not_configured", "exit_code": 2, "ai_action": "run_oauth_setup", "missing": [ {"item": "SLACK_USER_TOKEN", "required": true, "location": ".env"} ], "fix_instructions": [...], "setup_wizard": "python 00-system/skills/slack/slack-master/scripts/setup_slack.py" }

How Skills Reference This

Each skill loads shared resources only when needed (progressive disclosure):

slack-connect uses:

• check_slack_config.py (validate before any operation)

• All API scripts based on user request

• All references as needed

slack-send-message uses:

• check_slack_config.py (validate before sending)

• send_message.py (core functionality)

• error-handling.md (troubleshooting)

Environment Variables

Required in .env :

Slack User OAuth Token (starts with xoxp-)

SLACK_USER_TOKEN=xoxp-xxxxxxxxxxxxx

Optional: For OAuth setup flow

SLACK_CLIENT_ID=your-client-id SLACK_CLIENT_SECRET=your-client-secret

Required OAuth Scopes (User Token)

channels:read # List public channels channels:write # Create/manage public channels channels:history # Read public channel messages groups:read # List private channels groups:write # Create/manage private channels groups:history # Read private channel messages im:read # List DMs im:write # Manage DMs im:history # Read DM messages mpim:read # List group DMs mpim:write # Manage group DMs mpim:history # Read group DM messages chat:write # Send messages users:read # List users users:read.email # Get user emails files:read # List/download files files:write # Upload files reactions:read # Get reactions reactions:write # Add/remove reactions pins:read # List pinned items pins:write # Pin/unpin items search:read # Search messages/files reminders:read # List reminders reminders:write # Create/delete reminders team:read # Get team info

API Base URL

All API requests go to: https://slack.com/api/

Version: 1.0 Created: 2025-12-17 Status: Production Ready