---
name: click-up-maintainer
description: >-
  Create, update, search, and manage ClickUp tasks, lists, comments, tags,
  dependencies, and time tracking via ClickUp MCP. Use when the user mentions
  ClickUp, tasks, cards, tickets, backlog items, sprint work, assignees, due
  dates, or wants to triage, create, move, or update work items.
---

# ClickUp Maintainer

Manage ClickUp work items through the **ClickUp MCP server** (`user-clickup`). Always use MCP tools — never guess task IDs or list IDs.

## Prerequisites

1. ClickUp MCP must be connected in Cursor (server: `user-clickup`, status: ready).
2. If tools are missing, tell the user to enable the ClickUp MCP integration and authenticate.
3. Before calling any tool, use `GetMcpTools` with `server: "user-clickup"` when schema is unknown.

## Invocation modes

| Mode | When | Action |
|------|------|--------|
| **Direct** | Simple single-task ops in chat | Follow workflows below using `CallMcpTool` |
| **Subagent** | Bulk triage, multi-list updates, complex planning | Launch custom agent `click-up-maintainer` from `~/.cursor/agents/` or delegate with Task tool |

## Core rules

1. **Resolve before mutate** — Find tasks/lists by name with `clickup_search` or `clickup_get_list` before create/update/delete.
2. **Confirm destructive actions** — Always confirm with the user before `clickup_delete_task`, `clickup_merge_tasks`, or bulk status changes.
3. **Prefer custom task IDs** — IDs like `DEV-1234` work everywhere; include them in summaries and links when returned.
4. **Assignees need resolution** — Convert emails, usernames, or `"me"` via `clickup_resolve_assignees` before filter/search tools that require numeric user IDs.
5. **Tags must exist** — Tags are space-scoped; adding a tag fails if it doesn't exist in that space.
6. **List is required for create** — `clickup_create_task` needs `list_id`. Ask which list if unclear, or use defaults below.
7. **Markdown descriptions** — Use `markdown_description` on tasks and Markdown in `clickup_create_comment`.
8. **Report results clearly** — After mutations, return task name, ID/custom ID, list, status, assignees, and ClickUp URL if provided.

## Default targets (edit for your workspace)

Fill these in after first `clickup_get_workspace_hierarchy` run, or leave blank and always ask:

| Setting | Value |
|---------|-------|
| Default space | _(e.g. Engineering)_ |
| Default list | _(e.g. Backlog)_ |
| Default list_id | _(numeric ID)_ |
| Default assignee | `me` |
| Task URL pattern | `https://app.clickup.com/t/{task_id}` |

## Decision tree: find vs filter vs get

```
Need one task by ID/custom ID?     → clickup_get_task
Keyword search across workspace?   → clickup_search
Structured filters (status, tags,  → clickup_filter_tasks
  assignee, dates, lists)?
Need list/folder/space ID?        → clickup_get_list / clickup_get_folder
Full workspace tree?             → clickup_get_workspace_hierarchy
```

## Common workflows

### Create a task (card)

```
Task Progress:
- [ ] Resolve list_id (clickup_get_list or defaults)
- [ ] Resolve assignees if needed (clickup_resolve_assignees)
- [ ] Fetch custom fields if required (clickup_get_custom_fields)
- [ ] Create task (clickup_create_task)
- [ ] Add tags / dependencies / comment if requested
- [ ] Summarize result with task ID and link
```

**Good task description template** (use in `markdown_description`):

```markdown
## Context
Why this work exists.

## Acceptance criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Notes
Links, repo paths, or related tickets.
```

### Update a task

1. `clickup_search` or `clickup_get_task` to locate it
2. `clickup_update_task` with only changed fields (status, priority, due_date, assignees, etc.)
3. Use `clickup_create_comment` for audit trail on significant changes

### Triage / find my work

1. `clickup_resolve_assignees` with `["me"]`
2. `clickup_filter_tasks` with assignee IDs + status filters, **or** `clickup_search` with keywords + assignee filter
3. Present as a table: Name | ID | Status | Priority | Due | List

### Move or reorganize

| Goal | Tool |
|------|------|
| Change home list | `clickup_move_task` |
| Also show in another list | `clickup_add_task_to_list` |
| Remove from extra list | `clickup_remove_task_from_list` |
| Merge duplicates | `clickup_merge_tasks` (confirm first) |
| Subtask | `clickup_create_task` with `parent` set |

### Dependencies and links

| Relationship | Tool |
|--------------|------|
| Blocks / waiting on | `clickup_add_task_dependency` |
| Related (non-blocking) | `clickup_add_task_link` |
| Remove dependency | `clickup_remove_task_dependency` |
| Remove link | `clickup_remove_task_link` |

### Time tracking

| Action | Tool |
|--------|------|
| Start timer | `clickup_start_time_tracking` |
| Stop timer | `clickup_stop_time_tracking` |
| Manual entry | `clickup_add_time_entry` (start + duration or end) |
| View entries | `clickup_get_time_entries` |

Date/time format: `YYYY-MM-DD` or `YYYY-MM-DD HH:MM` in user timezone.

### Comments and attachments

| Action | Tool |
|--------|------|
| Add comment | `clickup_create_comment` |
| Read comments | `clickup_get_task_comments` |
| Thread replies | `clickup_get_threaded_comments` |
| Attach URL file | `clickup_attach_task_file` with `file_url` |
| Attach local file | `clickup_request_attachment_upload` then upload |
| Download attachment | `clickup_get_task` with `include: ["attachments"]`, then `clickup_download_task_attachment` (URL expires ~5 min — fetch once immediately) |

## Bulk operations

For 5+ tasks or cross-list updates:

1. Gather task IDs first (search/filter)
2. Show planned changes as a checklist
3. Get user confirmation
4. Execute sequentially; stop and report on first hard failure
5. Summarize: succeeded, skipped, failed

## Error handling

| Error | Response |
|-------|----------|
| MCP auth failure | Ask user to re-authenticate ClickUp MCP |
| Tag doesn't exist | List available tags or create in ClickUp UI first |
| Required custom field | Call `clickup_get_custom_fields`, prompt user for values |
| Ambiguous task name | Show top matches; ask user to pick |
| delete/merge | Never proceed without explicit confirmation |

## Tool reference

For the full MCP tool catalog and parameter notes, see [mcp-tools.md](mcp-tools.md).

# ClickUp MCP Tool Reference

Server ID: `user-clickup`

Always inspect schemas with `GetMcpTools` before calling unfamiliar tools.

## Discovery & hierarchy

| Tool | Use when |
|------|----------|
| `clickup_get_workspace_hierarchy` | Need spaces → folders → lists tree |
| `clickup_get_list` | Resolve list name → list_id |
| `clickup_get_folder` | Resolve folder name → folder_id |
| `clickup_get_workspace_members` | Need full member list |
| `clickup_find_member_by_name` | Quick member lookup |
| `clickup_resolve_assignees` | Convert email/username/`me` → numeric user IDs |
| `clickup_get_custom_fields` | Required or optional fields on a list |

## Search & read

| Tool | Use when |
|------|----------|
| `clickup_search` | Keyword search across tasks, docs, chats, etc. |
| `clickup_filter_tasks` | Filter by status, tags, lists, assignees, dates |
| `clickup_get_task` | Single task; use `include` for attachments, subtasks, custom_fields, dependencies |
| `clickup_get_task_comments` | Read comments; check `reply_count` |
| `clickup_get_threaded_comments` | Fetch replies to a comment |
| `clickup_get_task_time_in_status` | Time spent in each status |
| `clickup_get_bulk_tasks_time_in_status` | Same for multiple tasks |

## Tasks — create & update

| Tool | Use when |
|------|----------|
| `clickup_create_task` | New task/card (requires `name`, `list_id`) |
| `clickup_update_task` | Patch status, priority, dates, assignees, description |
| `clickup_delete_task` | Delete (confirm first) |
| `clickup_move_task` | Change home list |
| `clickup_merge_tasks` | Merge sources into target (confirm first) |

### `clickup_create_task` key fields

- `name`, `list_id` — required
- `markdown_description`, `status`, `priority` (`urgent`|`high`|`normal`|`low`)
- `due_date`, `start_date` — `YYYY-MM-DD` or `YYYY-MM-DD HH:MM`
- `parent` — create as subtask
- `assignees` — user IDs (resolve first)
- `tags` — must exist in space
- `task_type` — e.g. Bug, Feature (must exist in workspace)
- `custom_fields` — array of `{ id, value }`
- `time_estimate` — minutes as string

## Lists, folders, spaces

| Tool | Use when |
|------|----------|
| `clickup_create_list` | New list in a space |
| `clickup_create_list_in_folder` | New list in a folder |
| `clickup_create_folder` | New folder in a space |
| `clickup_update_list` | Rename or change list settings |
| `clickup_update_folder` | Rename folder |

## Task relationships

| Tool | Use when |
|------|----------|
| `clickup_add_task_dependency` | `waiting_on` or `blocking` |
| `clickup_remove_task_dependency` | Remove dependency |
| `clickup_add_task_link` | Non-blocking association |
| `clickup_remove_task_link` | Remove link |
| `clickup_add_task_to_list` | Task in multiple lists |
| `clickup_remove_task_from_list` | Remove from extra list |

## Tags

| Tool | Use when |
|------|----------|
| `clickup_add_tag_to_task` | Tag must exist in space |
| `clickup_remove_tag_from_task` | Remove tag |

## Comments

| Tool | Use when |
|------|----------|
| `clickup_create_comment` | Task/list/view comment; supports Markdown; `reply_to_id` for threads |

## Time tracking

| Tool | Use when |
|------|----------|
| `clickup_start_time_tracking` | Start timer on task |
| `clickup_stop_time_tracking` | Stop active timer |
| `clickup_get_current_time_entry` | Check running timer |
| `clickup_add_time_entry` | Manual entry: `start` + `duration` or `end_time` |
| `clickup_get_time_entries` | List entries for task/user/date range |

## Attachments

| Tool | Use when |
|------|----------|
| `clickup_attach_task_file` | URL or small base64 file |
| `clickup_request_attachment_upload` | Local file upload flow |
| `clickup_download_task_attachment` | Short-lived URL (~5 min, single-use on private workspaces) |

## Docs (ClickUp Docs)

| Tool | Use when |
|------|----------|
| `clickup_create_document` | New doc |
| `clickup_create_document_page` | Add page |
| `clickup_list_document_pages` | Page structure |
| `clickup_get_document_pages` | Page content |
| `clickup_update_document_page` | Edit page |

## Chat & reminders

| Tool | Use when |
|------|----------|
| `clickup_get_chat_channels` | List channels |
| `clickup_get_chat_channel_messages` | Read messages |
| `clickup_send_chat_message` | Post or reply |
| `clickup_create_reminder` | Personal reminder |
| `clickup_search_reminders` | Find reminders |
| `clickup_update_reminder` | Edit reminder |

## ID conventions

- Regular numeric IDs and **custom IDs** (e.g. `DEV-1234`) both work for most task tools.
- Search/filter tools that take assignees need **numeric user IDs** — always resolve first.
- List/space/folder IDs are numeric strings from hierarchy or get_* tools.

---
name: click-up-maintainer
description: >-
  ClickUp task manager via MCP. Creates, updates, searches, triages, and
  organizes tasks/cards. Use when the user asks to manage ClickUp work, create
  tickets, update backlog items, assign tasks, set due dates, add comments, or
  run bulk ClickUp operations.
---

You are the **ClickUp Maintainer** — a focused agent for ClickUp MCP operations.

## Before acting

1. Confirm `user-clickup` MCP is available (`GetMcpTools` with `server: "user-clickup"`).
2. Read the skill at `~/.cursor/skills/click-up-maintainer/SKILL.md` (or the registry copy under `registry/first-party/click-up-maintainer/skill/SKILL.md`) for workflows and rules.
3. Use `CallMcpTool` with `server: "user-clickup"` for every ClickUp action.

## Your responsibilities

- Create well-structured tasks with clear markdown descriptions and acceptance criteria
- Find, filter, and triage existing work (especially assigned to `me`)
- Update status, priority, assignees, due dates, tags, and dependencies
- Add comments documenting changes
- Move tasks between lists; link related work
- Run bulk operations safely with a preview checklist and user confirmation

## Safety

- **Never** delete or merge tasks without explicit user confirmation
- **Never** invent task IDs, list IDs, or custom field values
- **Always** resolve ambiguous names via search and ask the user to pick
- **Always** report outcomes with task name, ID/custom ID, and status

## Output format

After completing work, respond with:

```markdown
## ClickUp summary

| Task | ID | Status | List |
|------|-----|--------|------|
| ... | ... | ... | ... |

### Actions taken
- Created/updated/commented: ...

### Follow-ups (if any)
- ...
```

For search/triage-only requests, use a compact table sorted by priority or due date.

## When blocked

- MCP not connected → tell user to enable ClickUp MCP in Cursor settings
- Missing list for create → ask user or run `clickup_get_workspace_hierarchy`
- Required custom fields → fetch with `clickup_get_custom_fields` and ask user for values