Slack Search User Skill

Search for Slack users by username, real name, or display name with intelligent caching. This skill maintains a local cache of users to speed up lookups and can answer questions about the cache.

Features:

• ✅ Automatic status check - Verifies Slack is configured before searching
• ✅ Efficient cache lookup - Uses jq for fast searches even with 50,000+ users
• ✅ Automatic API fallback - Searches via Slack API if user not in cache
• ✅ Bulk caching - Caches ALL users from API responses (up to 1000 per request)
• ✅ Smart matching - Exact match first, then partial/contains match as fallback
• ✅ Cache introspection - Can answer questions like "how many users are cached?"

Usage

This skill provides two executable scripts:

1. search-user.sh - Find a specific user

Search for a Slack user by username, real name, or display name. Returns the user ID on stdout and details on stderr.

When the user asks:

• "Find user @fulano in Slack"
• "Search for Will in Slack"
• "Look up John Smith"
• "Is djalma in Slack?"

Run:

~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/skills/slack-search-user/search-user.sh <username>

Examples:

# Find user by exact username
~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/skills/slack-search-user/search-user.sh djalma
# Output: U01ULLNEM3Q

# Find user by real name
~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/skills/slack-search-user/search-user.sh "John Smith"

# Capture user ID in a variable
USER_ID=$(~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/skills/slack-search-user/search-user.sh fulano)
echo "User ID: $USER_ID"

How it works:

1. Checks Slack status first (calls slack-status)
2. Checks cache first using jq (fast, even with 50,000+ users)
3. First tries exact match (case-insensitive) on name, real_name, display_name
4. If no exact match, tries partial match (startswith/contains)
5. If still not found, searches via Slack API with pagination
6. Automatically caches ALL users from API response (up to 1000 per request)
7. Excludes bots and deleted users
8. Returns user ID on stdout for easy integration

Matching examples:

• djalma matches user with username djalma.araujo
• john matches John Smith in real name
• will matches William in display name

2. cache-utils.sh - Cache management

Inspect and manage the user cache.

When the user asks:

• "How many users are cached?"
• "List all users with 'john' in their name"
• "Clear the Slack cache"

Run:

~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/skills/slack-search-user/cache-utils.sh <command>

Commands:

# Count total cached users
~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/skills/slack-search-user/cache-utils.sh count
# Output: Total cached users: 12000

# List all cached users
~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/skills/slack-search-user/cache-utils.sh list

# Search for users matching a pattern
~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/skills/slack-search-user/cache-utils.sh search will

# Clear the cache
~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/skills/slack-search-user/cache-utils.sh clear

Configuration

This skill uses the centralized Slack plugin configuration at:

~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/config.json

The config file contains:

• workspace - Your Slack workspace domain
• token - Your session token (xoxc-...)
• cookie - Your session cookie (xoxd-...)
• users - Cached user array (auto-populated)

Status Check

Before searching, the skill automatically checks Slack status. If not configured:

⚠️  Slack is not properly configured
MISSING_CONFIG|Config file not found|Create config at: ~/.claude/plugins/marketplaces/djalmaaraujo-claude-code-plugins/plugins/slack/config.json

Please run: /slack:slack-setup

Integration with Other Skills

The slack-send-message skill uses this skill to find users for DMs.

Important Notes

• Automatic validation: Checks configuration before every search
• Shared cache: Cache is shared across all Slack skills in the plugin
• Efficient with large caches: Uses jq for streaming, works well with 50,000+ users
• Bulk caching: One API call can populate hundreds or thousands of users
• No duplicates: Automatically skips users already in cache
• Active users only: Excludes bots and deleted users from cache
• Requirements:
  • jq is required (install with brew install jq on macOS)
  • Python 3.6+ is required for API calls
  • Slack plugin must be configured (run /slack:slack-setup if needed)

Troubleshooting

Error	Solution
Slack is not properly configured	Run /slack:slack-setup to configure credentials
invalid_auth	Token or cookie expired. Re-run /slack:slack-setup
User 'X' not found	User doesn't exist or doesn't match any name fields
jq: command not found	Install jq: brew install jq (macOS) or apt install jq (Linux)
Python JSON decode error	Config file corrupted. Re-run /slack:slack-setup