| name | connect-slack |
| description | Skill for connecting a Slack channel to the Claude-Code-Tunnels Orchestrator. Guides Slack App creation, configures Socket Mode, collects credentials, and verifies the connection. Execute with /claude-code-tunnels:connect-slack. |
Connect Slack Channel
Adds a Slack channel to an existing Claude-Code-Tunnels Orchestrator.
Connects via Socket Mode (WebSocket), so no public IP or callback URL is required.
Rules
- Never proceed without asking the user
- Auto-detected values are presented as numbered choices first — the user only needs to enter a number
- If an existing credentials file is found, always confirm with the user before overwriting
- Credential files use the
key : value format (spaces on both sides of the colon)
- The ARCHIVE/ directory must not be committed to git
Step 0: Environment Preflight (CRITICAL)
Connecting Slack requires the orchestrator to be installed, pip packages present, and a credentials file.
Check each item in order — if any check fails, do not proceed to the next step until it is resolved.
0-1. Verify orchestrator.yaml
Why it is needed: the Slack adapter reads channel activation status and the ARCHIVE path from orchestrator.yaml. Without this file, adapter initialization will fail.
if [ ! -f "orchestrator.yaml" ]; then
echo "orchestrator.yaml not found."
echo "Please run /claude-code-tunnels:setup-orchestrator first."
fi
0-2. Verify ARCHIVE_PATH
Why it is needed: Slack credentials (app_id, bot_token, etc.) are stored in ARCHIVE/slack/credentials.
ARCHIVE_PATH=$(python3 -c "import yaml; print(yaml.safe_load(open('orchestrator.yaml')).get('archive', 'ARCHIVE'))")
Confirming credential storage path.
[1] $ARCHIVE_PATH <- value read from orchestrator.yaml
[2] Enter manually
Number:
0-3. Verify pip + packages
Why they are needed: slack-bolt (Socket Mode handler) and slack-sdk (Web API client) are required. Without them, from slack_bolt import ... will raise an ImportError.
$PYTHON_CMD -c "import slack_bolt" 2>/dev/null
$PYTHON_CMD -c "import slack_sdk" 2>/dev/null
If not installed:
The following packages required for Slack connection are not installed:
- slack-bolt (Socket Mode connection and event handling)
- slack-sdk (Slack Web API calls — message sending)
[1] Install now ($PIP_CMD install slack-bolt slack-sdk)
[2] Skip (install manually and continue)
Number:
0-4. Check for existing credentials
Why it is needed: if Slack is already configured, the user must decide whether to overwrite the existing setup.
if [ -f "$ARCHIVE_PATH/slack/credentials" ]; then
echo "Existing credentials found"
fi
If an existing file is found:
Existing Slack credentials already exist:
app_id: A0123...
bot_token: xoxb-...
[1] Overwrite (enter new values)
[2] Keep existing values (update configuration only)
[3] Cancel
Number:
Step 1: Slack App Setup Guide
If no Slack App exists yet, provide guidance:
Slack App Setup:
1. https://api.slack.com/apps → Create New App → "From scratch"
2. Set a name and select your workspace
3. Settings → Socket Mode → Enable Socket Mode
- Generate an App-level token (xapp-...) — connections:write scope
4. Event Subscriptions → Enable Events
- Subscribe: message.channels, app_mention
5. OAuth & Permissions → Bot Token Scopes:
- chat:write, channels:history, app_mentions:read
6. Install App to Workspace
7. Copy the Bot Token (xoxb-...)
Are you ready? (yes — start entering credentials / no — show detailed guide)
Step 2: Collect Credentials (6 fields)
Ask the user for each field one at a time. Empty values are not accepted.
Accompany each field prompt with a one-line explanation of why it is needed:
─────────────────────────────────────────────────────────────────
1. app_id
Shown on the Basic Information page of your Slack App settings.
Format: starts with A (e.g. A0123456789)
Enter:
2. client_id
Shown under Basic Information → App Credentials.
Format: number.number (e.g. 1234567890.1234567890)
Enter:
3. client_secret
Shown in the same App Credentials section. Click Show to copy it.
Enter:
4. signing_secret
Same App Credentials section. Used to verify the integrity of incoming bot requests.
Enter:
5. app_level_token
Generate under Settings → Basic Information → App-Level Tokens.
Used for authentication when establishing the Socket Mode connection.
Format: starts with xapp-
Validation: if it does not start with xapp- → "Invalid format. Please enter the full token starting with xapp-."
Enter:
6. bot_token
Found under OAuth & Permissions → Bot User OAuth Token.
Used to send messages (chat_postMessage).
Format: starts with xoxb-
Validation: if it does not start with xoxb- → "Invalid format."
Enter:
─────────────────────────────────────────────────────────────────
Summary after collection:
Slack Credentials entered:
app_id: A0123456789
client_id: 1234567890.1234567890
client_secret: ****
signing_secret: ****
app_level_token: xapp-1-...
bot_token: xoxb-...
Save with these values? (yes/no)
Step 3: Save Configuration
After user confirmation:
mkdir -p $ARCHIVE_PATH/slack/
cat > $ARCHIVE_PATH/slack/credentials << 'EOF'
app_id : $APP_ID
client_id : $CLIENT_ID
client_secret : $CLIENT_SECRET
signing_secret : $SIGNING_SECRET
app_level_token : $APP_LEVEL_TOKEN
bot_token : $BOT_TOKEN
EOF
Update orchestrator.yaml:
channels:
slack:
enabled: true
Step 4: Connection Test
cd $PROJECT_ROOT && ./start-orchestrator.sh --fg &
sleep 5
- Success → "Slack connection complete. Send a message to the bot in Slack to test it."
- Failure → show the error log to the user and analyze the cause. Do not retry automatically.
Credential File Format
app_id : A0123456789
client_id : 1234567890.1234567890
client_secret : abcdef1234567890
signing_secret : abcdef1234567890
app_level_token : xapp-1-A0123-1234567890-abcdef
bot_token : xoxb-1234567890-1234567890-abcdef
