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 operationsslack-send-message- Send messages to channels/DMsslack-list-channels- List available channelsslack-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.pyNo 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 --jsonStep 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-secretRequired 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 infoAPI Base URL
All API requests go to: https://slack.com/api/
Version: 1.0 Created: 2025-12-17 Status: Production Ready