---
name: slack-fetcher
description: Fetch Slack messages, threads, and lists by URL. Auto-detects URL type (message, list) and returns structured JSON ready for LLM processing. Use when needing to extract Slack context for analysis, documentation, or backlog items.
---

# Slack Fetcher

## Overview

Fetch Slack content by URL and automatically extract the full context. Supports two URL types:

- **Messages/threads** (`/archives/...`) — Returns message text, author, thread replies
- **Lists** (`/lists/...`) — Returns all list items with resolved column values (user names, dates, select labels)

## Quick Start

**Prerequisites:** See setup.md for token setup.

**Usage:**
```bash
cd ~/.claude/skills/slack-fetcher
uv run python slack_fetch.py "https://your-workspace.slack.com/archives/C12345/p1234567890123456"
```

**Output:** Structured JSON containing:
- `success`: Boolean status
- `author`, `channel`, `datetime`: Message metadata
- `text`: Full message content
- `is_thread`: Boolean (true if message has replies)
- `thread_replies`: Array of reply objects (if `is_thread=true`)

See output_schema.md for complete schema.

## Installation

1. Download all files from this gist into `~/.claude/skills/slack-fetcher/`
2. Create `slack_token.json` (see setup.md)
3. Install dependencies: `cd ~/.claude/skills/slack-fetcher && uv sync`
4. Test: `uv run python slack_fetch.py "https://your-workspace.slack.com/archives/..."`

## How It Works

1. **Parse URL** – Extract channel ID and timestamp from Slack URL
2. **Fetch Message** – Retrieve message from Slack API with user/channel info
3. **Check for Replies** – Query `conversations.replies` API to detect threads
4. **Fetch Thread** – If replies exist, fetch all thread replies with full context
5. **Return JSON** – Structured output ready for LLM processing

**Auto-Detection Logic:**
- If message has `thread_replies > 0` → `is_thread=true` and includes full thread
- If message is standalone → `is_thread=false` and `thread_replies=[]`

## Project Usage Examples

**Product Ops Intelligence (Backlog Extraction):**
When user pastes Slack discussion link into Claude Code:
```
User: "Add this to backlog: https://moiafamily.slack.com/archives/C09LRJSDZ4H/p1761840..."
Claude: [Runs slack_fetch.py] → Extracts thread context → Adds concise item to BACKLOG.md with link + full context
```

**Analysis & Documentation:**
When needing to preserve Slack discussions for later reference:
```
Claude: [Fetches thread] → Formats for markdown → Includes in project documentation
```

**Generic LLM Workflows:**
Any Claude instance can use fetched Slack data for analysis, summarization, or extraction without direct API access.

## Error Handling

**Common errors and causes:**

| Error | Cause | Solution |
|-------|-------|----------|
| "Invalid Slack URL format" | URL doesn't match expected pattern | Use direct Slack message URL from browser |
| "No token file found" | `slack_token.json` missing | See setup.md |
| "No access token found" | Token file malformed or empty | Verify token format in setup guide |
| "Slack API error: not_in_channel" | Bot doesn't have channel access | Add bot to channel in Slack workspace |

## Files

- **`SKILL.md`** – This file. Skill definition for Claude Code.
- **`slack_fetch.py`** – Main script. Handles URL parsing, message fetching, thread detection, and JSON output.
- **`setup.md`** – How to configure Slack token and obtain OAuth credentials.
- **`output_schema.md`** – Complete JSON response schema with examples (use for LLM context building).
- **`pyproject.toml`** – Python project config with dependencies.