Source Code

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 Elevated, Atrium, Winch Life, 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:

export CLICKUP_API_TOKEN="pk_your_token_here"

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

Basic Operations

List all workspaces:

python scripts/clickup_client.py get_teams

Create a task:

python scripts/clickup_client.py create_task list_id="123" name="New Task" status="to do"

Update a task:

python 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:

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

Common Workflows

Workflow: Create Task in Specific Workspace

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

Workflow: Configure Space Statuses

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

See API Reference for status configuration format.

Workflow: Track Time on Task

Option A - Manual Entry:

python scripts/clickup_client.py create_time_entry \
  team_id="xxx" \
  task_id="yyy" \
  duration=3600000 \
  description="Worked on feature"

Option B - Timer:

# Start timer
python scripts/clickup_client.py start_timer team_id="xxx" task_id="yyy"

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

Workflow: Create Document Structure

Create doc: create_doc workspace_id="xxx" name="Project Docs"
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):

python scripts/clickup_client.py task_counts team_id="xxx"
# Returns: {"total": 50, "parents": 20, "subtasks": 30, "unassigned": 5}

Get workload by assignee:

python scripts/clickup_client.py assignee_breakdown team_id="xxx"
# Returns: {"John Doe": 15, "Jane Smith": 12, "Unassigned": 8}

Get tasks by status:

python scripts/clickup_client.py status_breakdown team_id="xxx"
# Returns: {"to do": 20, "in progress": 10, "complete": 15}

Get tasks by priority:

python 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):

# All team members
python scripts/clickup_client.py standup_report team_id="xxx"

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

Get all tasks with pagination (auto-handled):

python scripts/clickup_client.py get_all_tasks team_id="xxx"
# Always includes subtasks automatically (critical!)

Filter reports by space or assignee:

# Specific space
python scripts/clickup_client.py task_counts team_id="xxx" space_ids='["90172290075"]'

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

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

Critical Rules for Reporting:

Always include subtasks — Our methods do this automatically via subtasks=true
Pagination handled — get_all_tasks loops until all pages retrieved
Parent vs Subtask — Parents have parent: null, subtasks have parent: "task_id"
Rate limit — 100 requests/min; our pagination respects this

Workflow: Link Doc to Task

Option A - Add as attachment:

python scripts/clickup_client.py link_doc_to_task \
  task_id="xxx" \
  doc_id="yyy"

Option B - Mention in description:

python 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:

# Task B is blocked by/waiting on Task A
python scripts/clickup_client.py add_dependency \
  task_id="TASK_B_ID" \
  depends_on="TASK_A_ID"

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

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

Set up reverse dependency (task is blocking another):

# Task A is blocking Task B
python 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:

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

# Remove link
python 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:

# Get tasks
TASKS=$(python 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:

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 folder
get_space_lists space_id="xxx" - Folderless lists
create_list folder_id="xxx" name="Name" [options...] - Create in folder
create_space_list space_id="xxx" name="Name" [options...] - Create folderless

Task Operations

get_task task_id="xxx" - Get task details (includes dependencies, linked tasks)
get_tasks list_id="xxx" [filters...] - List tasks
create_task list_id="xxx" name="Name" [options...] - Create task
update_task task_id="xxx" [options...] - Update task

Time Tracking

get_time_entries team_id="xxx" [filters...] - List entries
create_time_entry team_id="xxx" task_id="yyy" duration=3600000 [...] - Create entry
start_timer team_id="xxx" task_id="yyy" - Start timer
stop_timer team_id="xxx" - Stop timer

Documents (API v3)

get_docs workspace_id="xxx" - List documents
create_doc workspace_id="xxx" name="Name" [options...] - Create document
get_doc doc_id="xxx" - Get document details

Note on Pages: Doc pages API is in beta. Pages may need to be created via ClickUp UI.

Doc-Task Linking

link_doc_to_task task_id="xxx" doc_id="yyy" - Attach doc URL to task
mention_doc_in_task task_id="xxx" doc_id="yyy" - Add doc link to task description

Task Dependencies (Blocking/Waiting On)

add_dependency task_id="xxx" depends_on="yyy" - Task is blocked by/waiting on another task
add_dependency task_id="xxx" waiting_on="yyy" - Another task is blocked by/waiting on this task
remove_dependency task_id="xxx" depends_on="yyy" - Remove dependency
get_dependencies task_id="xxx" - List all dependencies for a task

Task Linking (Arbitrary Relationships)

link_tasks task_id="xxx" links_to="yyy" - Create arbitrary link between tasks
unlink_tasks task_id="xxx" links_to="yyy" - Remove task link

Reporting & Analytics

get_all_tasks team_id="xxx" [include_closed="true"] [space_ids='["id1"]'] [assignees='["uid1"]'] - All tasks with auto-pagination (always includes subtasks)
task_counts team_id="xxx" [filters...] - Count breakdown: total, parents, subtasks, unassigned
assignee_breakdown team_id="xxx" [filters...] - Workload distribution by assignee
status_breakdown team_id="xxx" [filters...] - Tasks grouped by status
priority_breakdown team_id="xxx" [filters...] - Tasks grouped by priority
standup_report team_id="xxx" [assignee_id="yyy"] - Daily standup report grouped by status

Documents

get_docs team_id="xxx" - List documents
create_doc team_id="xxx" name="Name" [options...] - Create document

Advanced Configuration

Custom Fields

To work with custom fields:

Get field definitions: GET /list/{list_id}/field (see API Reference)

Set values when creating/updating tasks:

python scripts/clickup_client.py update_task \
  task_id="xxx" \
  'custom_fields=[{"id":"field_id","value":"value"}]'

Status Configuration

When creating/updating spaces or lists:

python scripts/clickup_client.py update_space \
  space_id="xxx" \
  'statuses=[{"status":"To Do","type":"open"},{"status":"Done","type":"closed"}]'

Priority Levels

1 - Urgent
2 - High
3 - Normal
4 - Low

Error Handling

Common errors and solutions:

Error	Cause	Solution
`401 Unauthorized`	Invalid API token	Check CLICKUP_API_TOKEN
`404 Not Found`	Invalid ID	Verify workspace/space/folder/list/task IDs
`429 Too Many Requests`	Rate limit	Wait and retry (100 req/min limit)
`400 Bad Request`	Invalid parameters	Check JSON format in arguments

Python Client Usage

For complex operations, import the client directly:

from scripts.clickup_client import ClickUpClient

client = ClickUpClient()

# Get all workspaces
teams = client.get_teams()

# Create task with full control
task = client.create_task(
    list_id="123",
    name="Complex Task",
    description="Detailed description",
    assignees=[123, 456],
    tags=["urgent", "client"],
    priority=2,
    due_date=1704067200000,
    time_estimate=14400000
)

References

API Details: See references/api_reference.md for complete endpoint documentation, request/response formats, and field types.
ClickUp API Docs: https://clickup.com/api

Best Practices

Store IDs: Workspace/space/folder/list IDs rarely change. Store them in TOOLS.md for quick reference.
Custom Task IDs: If using custom IDs, always include custom_task_ids=true and team_id in task operations.
Rate Limiting: Space out bulk operations to avoid 429 errors.
Time Tracking: Use milliseconds for all duration/timestamp values.
Multi-Workspace: Always double-check team_id when working across workspaces to avoid modifying wrong workspace.

clickup-skill