clickup

What this skill does

# ClickUp Skill

**Enterprise-grade ClickUp integration for agency workflows.** Manage multiple clients, projects, and workspaces with advanced reporting, automatic subtask handling, and sophisticated folder organization.

## Key Benefits

| Feature | Why It Matters |
|---------|----------------|
| **🔍 Always includes subtasks** | Never miss 70%+ of actual work — subtasks included automatically |
| **📊 Advanced reporting** | Task counts, workload distribution, status breakdowns, standup reports |
| **🏢 Multi-workspace** | Seamlessly switch between Client Work, Product Development, Personal Projects, and more |
| **👥 Client organization** | Structured folders: 📋 Client Overview, 📁 Completed Work, active projects |
| **📈 Sales pipeline** | Track proposals, negotiations, and project lifecycles |
| **⏱️ Time tracking** | Built-in timers and manual entries with billing support |
| **📄 Document management** | Create docs and pages via API v3 |
| **🔗 Task relationships** | Dependencies, blocking/waiting, and arbitrary task linking |

## Quick Start

### Setup
Set your ClickUp API token:
```bash
export CLICKUP_API_TOKEN="pk_your_token_here"
```

Get your token from: ClickUp Settings → Apps → Generate API Token

### Basic Operations

**List all workspaces:**
```bash
python skills/clickup/scripts/clickup_client.py get_teams
```

**Create a task:**
```bash
python skills/clickup/scripts/clickup_client.py create_task list_id="123" name="New Task" status="to do"
```

**Update a task:**
```bash
python skills/clickup/scripts/clickup_client.py update_task task_id="abc" status="in progress"
```

## Workspace Hierarchy

```
Team (Workspace)
├── Spaces
│   ├── Folders
│   │   └── Lists → Tasks
│   └── Lists (Folderless) → Tasks
└── Documents
```

All operations require explicit workspace identification via IDs.

## Multi-Workspace Support

This skill supports operations across multiple ClickUp workspaces:

1. Use `get_teams` to list available workspaces
2. Reference workspace by `team_id` in operations
3. Each workspace maintains independent spaces, folders, lists
4. Custom task IDs require both `custom_task_ids=true` and `team_id`

## Common Workflows

### Workflow: Create Task in Specific Workspace

1. Get workspace ID: `get_teams`
2. Get target space: `get_spaces team_id="xxx"`
3. Get or create list: `get_folders space_id="yyy"` → `get_lists folder_id="zzz"`
4. Create task: `create_task list_id="aaa" name="Task" ...`

### Workflow: Configure Space Statuses

1. Get space: `get_space space_id="xxx"`
2. Update space with statuses: `update_space space_id="xxx" statuses=[...]`

See [API Reference](references/api_reference.md) for status configuration format.

### Workflow: Track Time on Task

**Option A - Manual Entry:**
```bash
python skills/clickup_client.py create_time_entry \
  team_id="xxx" \
  task_id="yyy" \
  duration=3600000 \
  description="Worked on feature"
```

**Option B - Timer:**
```bash
# Start timer
python skills/clickup/scripts/clickup_client.py start_timer team_id="xxx" task_id="yyy"

# Stop timer (stops current running timer for user)
python skills/clickup/scripts/clickup_client.py stop_timer team_id="xxx"
```

### Workflow: Create Document Structure

1. Create doc: `create_doc workspace_id="xxx" name="Project Docs"`
2. Add pages: Use ClickUp UI (pages API is in beta)

Note: Documents use ClickUp API v3 (workspace_id instead of team_id).

### Workflow: Reporting & Analytics

**Get task counts (with parent/subtask breakdown):**
```bash
python skills/clickup/scripts/clickup_client.py task_counts team_id="xxx"
# Returns: {"total": 50, "parents": 20, "subtasks": 30, "unassigned": 5}
```

**Get workload by assignee:**
```bash
python skills/clickup/scripts/clickup_client.py assignee_breakdown team_id="xxx"
# Returns: {"John Doe": 15, "Jane Smith": 12, "Unassigned": 8}
```

**Get tasks by status:**
```bash
python skills/clickup/scripts/clickup_client.py status_breakdown team_id="xxx"
# Returns: {"to do": 20, "in progress": 10, "complete": 15}
```

**Get tasks by priority:**
```bash
python skills/clickup/scripts/clickup_client.py priority_breakdown team_id="xxx"
# Returns: {"urgent": 2, "high": 5, "normal": 15, "low": 8, "none": 20}
```

**Daily standup report (grouped by status):**
```bash
# All team members
python skills/clickup/scripts/clickup_client.py standup_report team_id="xxx"

# Specific person (use user ID)
python skills/clickup/scripts/clickup_client.py standup_report team_id="xxx" assignee_id="12345"
```

**Get all tasks with pagination (auto-handled):**
```bash
python skills/clickup/scripts/clickup_client.py get_all_tasks team_id="xxx"
# Always includes subtasks automatically (critical!)
```

**Filter reports by space or assignee:**
```bash
# Specific space
python skills/clickup/scripts/clickup_client.py task_counts team_id="xxx" space_ids='["SPACE_ID_HERE"]'

# Specific assignee
python skills/clickup/scripts/clickup_client.py get_all_tasks team_id="xxx" assignees='["12345"]'

# Include closed tasks
python skills/clickup/scripts/clickup_client.py task_counts team_id="xxx" include_closed="true"
```

**Critical Rules for Reporting:**
1. **Always include subtasks** — Our methods do this automatically via `subtasks=true`
2. **Pagination handled** — `get_all_tasks` loops until all pages retrieved
3. **Parent vs Subtask** — Parents have `parent: null`, subtasks have `parent: "task_id"`
4. **Rate limit** — 100 requests/min; our pagination respects this

### Workflow: Link Doc to Task

**Option A - Add as attachment:**
```bash
python skills/clickup/scripts/clickup_client.py link_doc_to_task \
  task_id="xxx" \
  doc_id="yyy"
```

**Option B - Mention in description:**
```bash
python skills/clickup/scripts/clickup_client.py mention_doc_in_task \
  task_id="xxx" \
  doc_id="yyy"
```

Both create clickable links to the document from the task.

### Workflow: Task Dependencies

**Set up blocking relationship:**
```bash
# Task B is blocked by/waiting on Task A
python skills/clickup/scripts/clickup_client.py add_dependency \
  task_id="TASK_B_ID" \
  depends_on="TASK_A_ID"

# Check dependencies
python skills/clickup/scripts/clickup_client.py get_dependencies \
  task_id="TASK_B_ID"

# Remove dependency
python skills/clickup/scripts/clickup_client.py remove_dependency \
  task_id="TASK_B_ID" \
  depends_on="TASK_A_ID"
```

**Set up reverse dependency (task is blocking another):**
```bash
# Task A is blocking Task B
python skills/clickup/scripts/clickup_client.py add_dependency \
  task_id="TASK_A_ID" \
  waiting_on="TASK_B_ID"
```

### Workflow: Link Related Tasks (Non-Dependency)

For related tasks that aren't blocking each other:

```bash
# Link Task A to Task B (arbitrary relationship)
python skills/clickup/scripts/clickup_client.py link_tasks \
  task_id="TASK_A_ID" \
  links_to="TASK_B_ID"

# Remove link
python skills/clickup/scripts/clickup_client.py unlink_tasks \
  task_id="TASK_A_ID" \
  links_to="TASK_B_ID"
```

Note: `link_tasks` creates a "linked task" relationship (appears in task's "Linked Tasks" section), while `add_dependency` creates blocking/waiting relationships.

### Workflow: Bulk Task Operations

For bulk operations, loop through tasks:
```bash
# Get tasks
TASKS=$(python skills/clickup/scripts/clickup_client.py get_tasks list_id="xxx")

# Process each (parse JSON and loop)
```

## Script Reference

### scripts/clickup_client.py

Main CLI interface for ClickUp operations.

**Usage:**
```bash
python scripts/clickup_client.py <command> [key=value ...]
```

**Commands:**

#### Workspace Operations
- `get_teams` - List all accessible workspaces

#### Space Operations
- `get_spaces team_id="xxx"` - List spaces
- `create_space team_id="xxx" name="Name" [options...]` - Create space
- `update_space space_id="xxx" [options...]` - Update space

#### Folder Operations
- `get_folders space_id="xxx"` - List folders
- `create_folder space_id="xxx" name="Name"` - Create folder

#### List Operations
- `get_lists folder_id="xxx"` - Lists in folde