How do I install the Clickup skill?

Run npx skillmds add majiayu000/clickup in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Clickup skill do?

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. It is listed under Productivity on SkillMD.

Is Clickup safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Clickup?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Clickup free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Clickup?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Clickup by majiayu000 — Agent Skill

Name: Clickup
Rating: 4.666666666666667 (3 reviews)
Author: majiayu000

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

Copy .env-example to .env in this skill directory
Add your ClickUp Personal API Token (starts with pk_)
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

Command	Description
`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

Command	Description
`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

Flag	Description
`--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"

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:

Feature	API Version	Content Format
Comments	v2	Proprietary JSON array (converted via `markdownToClickUp()`)
Task descriptions	v2	Native markdown via `markdown_description` field
Docs/Pages	v3	Native 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).

Clickup

File contents

ClickUp

Setup

Default List (Optional)

Running Commands

Task Commands

Document Commands

Options

Examples

Get Task Details

Create a Task

List My Tasks

Search Tasks

Update Task Status

Assign Tasks

Set Due Dates

Set Priority

Create Subtasks

Move Tasks

Add Links

Add Checklist Items

List Tasks in a List

View Comments

Post a Comment

Show Current User

Delete a Comment

Notify Users (Watch)

Add Tags

Update Description

List/Search Docs

Get Doc Details

Create a Doc

Get Page Content

Create a Page

Edit a Page

Task/List/Doc URL Formats

Output Format

Task Details

Task List

Comments

Doc Details

Page Content

When to Use

Tips

Technical Notes

Markdown Handling

Doc Page Structure

Related skills

Frequently asked questions

How do I install the Clickup skill?

What does the Clickup skill do?

Is Clickup safe to use?

Which AI agents work with Clickup?

Is Clickup free to use?

Who published Clickup?