OpenSkillIndex← back to search
claude-code

Claude-skill-registry clickup

Interact with ClickUp tasks and documents - get task details, view comments, create and manage tasks, create and edit docs. Use when working with ClickUp task/doc URLs or IDs.

install
source · Clone the upstream repo
git clone https://github.com/majiayu000/claude-skill-registry
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/clickup" ~/.claude/skills/majiayu000-claude-skill-registry-clickup && rm -rf "$T"
manifest: skills/data/clickup/SKILL.md
source content

ClickUp

Interact with ClickUp tasks and documents via the API. Get task information, view comments, create tasks, manage assignments, post updates, and create/edit documents.

Setup

  1. Copy 
    .env-example
    to 
    .env
    in this skill directory
  2. Add your ClickUp Personal API Token (starts with 
    pk_
    )
  3. Generate token at: ClickUp Settings > Apps > API Token
cp .claude/skills/clickup/.env-example .claude/skills/clickup/.env
# Edit .env and add your token

Team ID and User ID are auto-detected and cached on first use.

Default List (Optional)

Set 

CLICKUP_DEFAULT_LIST_ID
in 
.env
to enable creating tasks without specifying a list:

# In .claude/skills/clickup/.env
CLICKUP_DEFAULT_LIST_ID=901111220963

Running Commands

node .claude/skills/clickup/query.mjs <command> [options]

Task Commands

CommandDescription
get <url|id>
Get task details (name, description, status, assignees, etc.)
comments <url|id>
List comments on a task
comment <url|id> "message"
Post a comment to a task (supports markdown)
status <url|id> [status]
Update task status (or list available statuses)
tasks <list_id>
List tasks in a list
me
Show current user info
create [list_id] "title"
Create a new task (list_id optional if default set)
my-tasks
List all tasks assigned to you across workspace
search "query"
Search tasks by name or description
assign <task> <user>
Assign task to a user (by name, email, or ID)
due <task> "date"
Set due date (e.g., "tomorrow", "friday", "+3d")
priority <task> <level>
Set priority (urgent, high, normal, low, none)
subtask <task> "title"
Create a subtask
move <task> <list_id>
Move task to a different list
link <task> <url> ["desc"]
Add external link reference (as comment)
checklist <task> "item"
Add checklist item to task
delete-comment <comment_id>
Delete a comment
watch <task> <user>
Notify user via @mention comment (watchers not supported in API)
tag <task> "tag_name"
Add a tag to task
description <task> "text"
Update task description (markdown supported)

Document Commands

CommandDescription
docs ["query"]
Search/list docs in workspace (optional search query)
doc <doc_id>
Get doc details and page listing
create-doc "title"
Create a new doc (use 
--content
for initial content)
page <doc_id> <page_id>
Get page content (markdown format)
create-page <doc_id> "title"
Add a new page to a doc (creates additional page)
edit-page <doc_id> <page_id>
Edit a page's content or name

Options

FlagDescription
--json
Output raw JSON response
--subtasks
Include subtasks when getting task details
--me
Filter to tasks assigned to me (for tasks command)
--content
, 
-c
Page content for create-page/edit-page (markdown)
--name
, 
-n
New page name for edit-page

Examples

Get Task Details

# Using full URL
node .claude/skills/clickup/query.mjs get "https://app.clickup.com/t/86a1b2c3d"

# Using task ID directly
node .claude/skills/clickup/query.mjs get 86a1b2c3d

# Include subtasks
node .claude/skills/clickup/query.mjs get 86a1b2c3d --subtasks

Create a Task

# With explicit list ID
node .claude/skills/clickup/query.mjs create 901111220963 "New feature: dark mode"

# Using default list (if CLICKUP_DEFAULT_LIST_ID is set)
node .claude/skills/clickup/query.mjs create "Quick task"

List My Tasks

# All tasks assigned to you across the workspace
node .claude/skills/clickup/query.mjs my-tasks

Search Tasks

node .claude/skills/clickup/query.mjs search "authentication"

Update Task Status

# List available statuses for a task
node .claude/skills/clickup/query.mjs status 86a1b2c3d

# Update status (case-insensitive, partial match)
node .claude/skills/clickup/query.mjs status 86a1b2c3d "in progress"
node .claude/skills/clickup/query.mjs status 86a1b2c3d "complete"

Assign Tasks

# Assign by username
node .claude/skills/clickup/query.mjs assign 86a1b2c3d justin

# Assign by email
node .claude/skills/clickup/query.mjs assign 86a1b2c3d jane@example.com

Set Due Dates

node .claude/skills/clickup/query.mjs due 86a1b2c3d "tomorrow"
node .claude/skills/clickup/query.mjs due 86a1b2c3d "next friday"
node .claude/skills/clickup/query.mjs due 86a1b2c3d "+3d"
node .claude/skills/clickup/query.mjs due 86a1b2c3d "2024-01-15"

Set Priority

node .claude/skills/clickup/query.mjs priority 86a1b2c3d urgent
node .claude/skills/clickup/query.mjs priority 86a1b2c3d high
node .claude/skills/clickup/query.mjs priority 86a1b2c3d none  # Clear priority

Create Subtasks

node .claude/skills/clickup/query.mjs subtask 86a1b2c3d "Write unit tests"
node .claude/skills/clickup/query.mjs subtask 86a1b2c3d "Update documentation"

Move Tasks

node .claude/skills/clickup/query.mjs move 86a1b2c3d 901111220964

Add Links

# Add link with description
node .claude/skills/clickup/query.mjs link 86a1b2c3d "https://github.com/..." "PR #123"

# Add link without description
node .claude/skills/clickup/query.mjs link 86a1b2c3d "https://docs.example.com/guide"

Add Checklist Items

node .claude/skills/clickup/query.mjs checklist 86a1b2c3d "Review code"
node .claude/skills/clickup/query.mjs checklist 86a1b2c3d "Run tests"
node .claude/skills/clickup/query.mjs checklist 86a1b2c3d "Deploy to staging"

List Tasks in a List

# All tasks in a list
node .claude/skills/clickup/query.mjs tasks 901111220963

# Only tasks assigned to me
node .claude/skills/clickup/query.mjs tasks 901111220963 --me

View Comments

node .claude/skills/clickup/query.mjs comments "https://app.clickup.com/t/86a1b2c3d"

Post a Comment

node .claude/skills/clickup/query.mjs comment 86a1b2c3d "Starting work on this task"

# Multi-line comment
node .claude/skills/clickup/query.mjs comment 86a1b2c3d "Status update:
- Completed initial review
- Found 3 issues to address
- Will submit PR by EOD"

Show Current User

node .claude/skills/clickup/query.mjs me

Delete a Comment

# Get comment IDs from the comments command (shown in --json output)
node .claude/skills/clickup/query.mjs delete-comment 90110200841741

Notify Users (Watch)

# Notify user via @mention comment (ClickUp API doesn't support adding watchers directly)
node .claude/skills/clickup/query.mjs watch 86a1b2c3d koen

# Notify by email
node .claude/skills/clickup/query.mjs watch 86a1b2c3d jane@example.com

Add Tags

# Add a tag to a task
node .claude/skills/clickup/query.mjs tag 86a1b2c3d "DevOps"
node .claude/skills/clickup/query.mjs tag 86a1b2c3d "bug"

Update Description

# Update task description with markdown
node .claude/skills/clickup/query.mjs description 86a1b2c3d "## Summary
This is a **bold** statement.

- Item 1
- Item 2

See [documentation](https://example.com) for more info."

List/Search Docs

# List all docs in workspace
node .claude/skills/clickup/query.mjs docs

# Search docs by name
node .claude/skills/clickup/query.mjs docs "API"

Get Doc Details

# Get doc info and page listing
node .claude/skills/clickup/query.mjs doc abc123def

# Using a doc URL
node .claude/skills/clickup/query.mjs doc "https://app.clickup.com/12345/v/dc/abc123def"

Create a Doc

# Create an empty doc
node .claude/skills/clickup/query.mjs create-doc "Project Notes"

# Create a doc with initial content (populates the first page)
node .claude/skills/clickup/query.mjs create-doc "API Documentation" --content "# API Documentation

This document covers the API endpoints and usage.

## Overview
..."

Get Page Content

# Get a specific page's content
node .claude/skills/clickup/query.mjs page abc123def page456

Create a Page

# Create a page with just a title
node .claude/skills/clickup/query.mjs create-page abc123def "New Section"

# Create a page with content
node .claude/skills/clickup/query.mjs create-page abc123def "Getting Started" --content "# Welcome

This is the getting started guide.

## Prerequisites
- Node.js 18+
- npm or yarn"

Edit a Page

# Update page content
node .claude/skills/clickup/query.mjs edit-page abc123def page456 --content "Updated content here"

# Rename a page
node .claude/skills/clickup/query.mjs edit-page abc123def page456 --name "New Page Name"

# Update both content and name
node .claude/skills/clickup/query.mjs edit-page abc123def page456 --content "New content" --name "New Name"

Task/List/Doc URL Formats

The skill recognizes these ClickUp URL formats:

Tasks:

  • https://app.clickup.com/t/{task_id}
  • https://app.clickup.com/{team_id}/v/li/{list_id}?p={task_id}
  • Direct task ID: 
    86a1b2c3d

Lists:

  • https://app.clickup.com/{team_id}/v/li/{list_id}
  • Direct list ID: 
    901111220963

Docs:

  • https://app.clickup.com/{team_id}/v/dc/{doc_id}
  • https://app.clickup.com/{team_id}/docs/{doc_id}
  • Direct doc ID: 
    abc123def

Output Format

Task Details

Task: Implement user authentication
Status: In Progress
Priority: High
Assignees: John Doe, Jane Smith
Due: 2024-01-15
Created: 2024-01-10
URL: https://app.clickup.com/t/86a1b2c3d

Description:
Add OAuth2 authentication with Google and GitHub providers...

Task List

[to do] Fix login bug
  ID: 868h2cxat | Priority: high | Assignees: John Doe
  https://app.clickup.com/t/868h2cxat

[in progress] Update API docs
  ID: 868g7c75u | Priority: None | Assignees: Jane Smith
  https://app.clickup.com/t/868g7c75u

Total: 2 task(s)

Comments

[2024-01-12 14:30] John Doe:
  Started working on this. Will push initial commit today.

[2024-01-12 16:45] Jane Smith:
  @John looks good! Let me know when ready for review.

Doc Details

Doc: API Documentation
ID: abc123def
Created: Jan 10, 2024, 09:30 AM
Updated: Jan 15, 2024, 02:45 PM
Creator: John Doe
Workspace: 12345678

Pages:
Introduction
  ID: page001

Getting Started
  ID: page002

API Reference
  ID: page003

Total: 3 page(s)

Page Content

Page: Getting Started
ID: page002
Created: Jan 10, 2024, 10:00 AM
Updated: Jan 14, 2024, 03:30 PM

Content:
---
# Getting Started

Welcome to the API documentation.

## Prerequisites
- Node.js 18+
- An API key
---

When to Use

Tasks:

  • Understanding context: Get task details before starting work
  • Quick task creation: Create tasks without leaving your terminal
  • Daily standups: Use 
    my-tasks
    to see your assignments
  • Status updates: Post progress comments as you work
  • Task management: Assign, prioritize, and set due dates
  • Collaboration: View recent comments for context, add watchers
  • Task organization: Add tags to categorize tasks
  • Task linking: Reference task IDs in commit messages

Documents:

  • Documentation: Create and maintain project documentation
  • Knowledge base: Build reference guides and wikis
  • Meeting notes: Store meeting notes and decisions
  • Specifications: Write and update technical specs
  • Quick edits: Update doc content without leaving the terminal

Tips

  • Team ID, User ID, and default list ID are auto-cached in 
    .env
  • Set 
    CLICKUP_DEFAULT_LIST_ID
    to skip list_id when creating team tasks
  • Use 
    my-tasks
    for a quick overview of your assignments
  • Use natural language dates: "tomorrow", "next friday", "+3d"
  • Post comments to keep stakeholders updated on progress
  • Include task IDs in commit messages for traceability
  • Use 
    --json
    for scripting or piping to other tools
  • Doc content uses markdown format for both input and output
  • The Docs API uses v3 endpoints (workspace-based instead of team-based)

Technical Notes

Markdown Handling

ClickUp uses different content formats for different features:

FeatureAPI VersionContent Format
Commentsv2Proprietary JSON array (converted via 
markdownToClickUp()
)
Task descriptionsv2Native markdown via 
markdown_description
field
Docs/Pagesv3Native markdown (no conversion needed)

The Docs API (v3) accepts and returns markdown directly, so no conversion is required. This is different from comments which use a proprietary format that requires the 

lib/markdown.mjs
conversion utilities.

Doc Page Structure

When you create a doc via the API, ClickUp automatically creates an empty first page. This has implications:

  • create-doc
     - Creates a doc with an auto-generated first page. Use 
    --content
    to populate that first page.
  • create-page
     - Adds an additional page to a doc (second page, third page, etc.)
  • edit-page
     - Modifies an existing page's content

To add content to a new doc, use 

create-doc "Title" --content "..."
rather than creating the doc and then using 
create-page
(which would leave the first page empty).