clickup-agent-cli 0.2.0

package/skills/clickup-tasks/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: clickup-tasks
+description: Creates, updates, searches, and manages ClickUp tasks, subtasks, checklists, dependencies, and attachments. Use when the user asks about tasks, wants to create or find work items, manage subtasks, add checklists, set dependencies, or upload files to tasks.
+allowed-tools: Bash(clickup task *), Bash(clickup checklist *), Bash(clickup dependency *), Bash(clickup relation *), Bash(clickup attachment *), Bash(clickup schema tasks*), Bash(clickup schema checklist*)
+---
+
+# ClickUp Tasks
+
+Manage the full task lifecycle: create, list, search, update, delete. Also covers subtasks, checklists, dependencies, relations, and attachments.
+
+## Task Commands
+
+### List tasks in a list
+```bash
+clickup task list --list-id <id> [--status <s>...] [--assignee <id>...] [--tag <name>...]
+    [--due-date-gt <ts>] [--due-date-lt <ts>] [--include-closed] [--subtasks]
+    [--order-by <id|created|updated|due_date>] [--reverse] [--page <n>]
+```
+
+### Search tasks across workspace
+```bash
+clickup task search --workspace-id <id> [--query <text>] [--status <s>...]
+    [--assignee <id>...] [--list-id <id>...] [--space-id <id>...] [--priority <1-4>...]
+    [--due-date-gt <ts>] [--due-date-lt <ts>] [--include-closed] [--page <n>]
+```
+
+### Get a single task
+```bash
+clickup task get <task-id> [--include-subtasks] [--include-markdown-description]
+```
+
+### Create a task
+```bash
+clickup task create --list-id <id> --name <name>
+    [--description <text>] [--markdown-description <md>]
+    [--status <s>] [--priority <1-4>] [--due-date <ts>] [--start-date <ts>]
+    [--assignee <id>...] [--tag <name>...] [--time-estimate <ms>]
+    [--parent <task-id>] [--custom-field <id=value>...]
+```
+
+### Update a task
+```bash
+clickup task update <task-id> [--name <name>] [--description <text>]
+    [--status <s>] [--priority <1-4>] [--due-date <ts>] [--start-date <ts>]
+    [--assignee-add <id>...] [--assignee-remove <id>...] [--archived <bool>]
+```
+
+### Delete a task
+```bash
+clickup task delete <task-id> --confirm
+```
+
+### Time in status
+```bash
+clickup task time-in-status <task-id>
+clickup task bulk-time-in-status --task-id <id>...
+```
+
+## Checklist Commands
+
+```bash
+clickup checklist create --task-id <id> --name <name>
+clickup checklist update <checklist-id> [--name <name>] [--position <n>]
+clickup checklist delete <checklist-id> --confirm
+clickup checklist add-item <checklist-id> --name <name> [--assignee <id>] [--resolved <bool>]
+clickup checklist update-item <checklist-id> --item-id <id> [--name <name>] [--resolved <bool>]
+clickup checklist delete-item <checklist-id> --item-id <id>
+```
+
+## Dependency Commands
+
+```bash
+# Task A depends on (is blocked by) Task B
+clickup dependency add --task-id <A> --depends-on <B>
+
+# Task A blocks Task B
+clickup dependency add --task-id <A> --dependency-of <B>
+
+# Remove dependency
+clickup dependency remove --task-id <A> --depends-on <B>
+```
+
+## Relation Commands
+
+```bash
+clickup relation add --task-id <id> --links-to <id>
+clickup relation remove --task-id <id> --links-to <id>
+```
+
+## Attachment Commands
+
+```bash
+clickup attachment upload --task-id <id> --file <path> [--filename <name>]
+```
+
+## Common Patterns
+
+```bash
+# Create a subtask
+clickup task create --list-id <id> --name "Subtask" --parent <parent-task-id>
+
+# Find overdue tasks
+clickup task list --list-id <id> --due-date-lt $(date +%s000) --include-closed false
+
+# Create task and immediately comment
+TASK_ID=$(clickup task create --list-id <id> --name "Bug fix" --format id)
+clickup comment create --task-id "$TASK_ID" --text "Starting investigation"
+
+# Bulk get tasks by ID
+clickup task list --list-id <id> --format quiet | xargs -I{} clickup task get {}
+
+# Render task list as markdown table (for display in chat or docs)
+clickup task list --list-id <id> --format md
+
+# Send task list to a chat channel
+clickup chat send --channel-id <id> --message "$(clickup task list --list-id <id> --format md)"
+```
+
+## Discovery
+
+```bash
+clickup schema tasks              # List all task actions
+clickup schema tasks.create       # Show create fields
+clickup schema tasks.list         # Show list filter flags
+```

package/skills/clickup-team-report/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: clickup-team-report
+description: Generates a status report for any team, department, or area of the business in ClickUp. Covers task progress, workload distribution, upcoming deadlines, and highlights. Use when the user asks for a department rundown, team status, what marketing is doing, operations update, or any team/department-specific report.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[team or department name, e.g. 'marketing', 'engineering', 'operations']"
+allowed-tools: Bash(clickup *)
+---
+
+# Team / Department Report
+
+Generate a status report for any team, department, or area of the business. This recipe adapts to whatever scope the user asks about.
+
+## Understanding the Request
+
+`$ARGUMENTS` tells you what team or area to report on. This could be:
+
+- A department name: "marketing", "engineering", "finance", "operations", "HR"
+- A team name: "backend team", "design team", "QA"
+- A project name: "website redesign", "Q1 launch"
+- A space or folder name that maps to an area of the business
+- A combination: "what's the marketing team working on this sprint"
+
+## Workflow
+
+### Step 1: Find the right scope
+
+```bash
+# List all spaces to find one matching the team/department
+clickup space list --format json
+
+# If the team maps to a folder within a space
+clickup folder list --space-id <id> --format json
+
+# If the team maps to specific lists
+clickup list list --folder-id <id> --format json
+```
+
+Match the user's request to the appropriate space, folder, or list. A "marketing" request might match a "Marketing" space, a "Marketing" folder within a broader space, or multiple lists tagged for marketing work.
+
+### Step 2: Get current task breakdown
+
+```bash
+# Get all active tasks in the identified scope
+clickup task list --list-id <id> --format json
+
+# Or search across the space
+clickup task search --workspace-id <id> --space-id <space-id> --format json
+```
+
+### Step 3: Analyze workload distribution
+
+```bash
+# Get tasks grouped by status to understand the pipeline
+clickup task search --workspace-id <id> --space-id <space-id> \
+  --status "to do" --format json
+
+clickup task search --workspace-id <id> --space-id <space-id> \
+  --status "in progress" --format json
+
+clickup task search --workspace-id <id> --space-id <space-id> \
+  --status "complete" --status "closed" \
+  --date-updated-gt <week-start-ms> \
+  --format json
+```
+
+### Step 4: Check upcoming deadlines
+
+```bash
+# Tasks due in the next 7 days
+clickup task search --workspace-id <id> --space-id <space-id> \
+  --due-date-gt <now-ms> --due-date-lt <next-week-ms> \
+  --include-closed false \
+  --format json
+```
+
+### Step 5: Find blockers and risks
+
+```bash
+# Overdue tasks
+clickup task search --workspace-id <id> --space-id <space-id> \
+  --due-date-lt <now-ms> --include-closed false \
+  --format json
+
+# Blocked tasks
+clickup task search --workspace-id <id> --space-id <space-id> \
+  --status "blocked" --status "waiting" \
+  --format json
+```
+
+### Step 6: Check time investment (if relevant)
+
+```bash
+clickup time list --workspace-id <id> \
+  --start <week-start-ms> --end <now-ms> \
+  --format json
+```
+
+Filter time entries to those related to the team's tasks.
+
+### Step 7: Compile the report
+
+Structure the report as:
+
+- **Team/Department**: Name and scope of what is covered
+- **Summary**: 2-3 sentence overview of where things stand
+- **By the numbers**: Task counts (to do / in progress / done this week)
+- **Key accomplishments**: Notable completed tasks
+- **Currently working on**: In-progress items with assignees
+- **Upcoming deadlines**: Tasks due in the next 7 days
+- **Risks and blockers**: Overdue or blocked items needing attention
+- **Time invested**: Hours logged this period (if time tracking is used)
+
+## Adapting to the Request
+
+The user might ask in many different ways. All of these should work:
+
+- "What's marketing up to?" -> Find marketing space, broad status report
+- "Give me an engineering rundown" -> Engineering space, technical focus
+- "How's the Q1 launch going?" -> Find matching project/folder, progress focus
+- "Operations team status" -> Operations space/folder, operational metrics
+- "What is Sarah's team working on?" -> Find Sarah, get her team's space, report
+- "Finance department this month" -> Finance space, expand date range to month
+
+## Tips
+
+- If a team doesn't map cleanly to one space, check folders and lists too
+- Some organizations use tags instead of spaces for departments
+- When the scope is ambiguous, report on the best match and mention what was included
+- The user can always refine: "actually just the paid ads list within marketing"

package/skills/clickup-time/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: clickup-time
+description: Tracks time in ClickUp including logging entries, managing running timers, tagging time, and querying reports. Use when the user asks about time tracking, wants to start or stop a timer, log hours, check who is working on what, or audit time entries.
+allowed-tools: Bash(clickup time *), Bash(clickup schema time*)
+---
+
+# ClickUp Time Tracking
+
+Log time entries, manage running timers, tag time, and query time data.
+
+## Time Entry Commands
+
+### List entries
+```bash
+clickup time list --task-id <id> [--start <date>] [--end <date>]
+clickup time list --workspace-id <id> --start <date> --end <date> [--assignee <id>...]
+```
+
+### Create / Update / Delete
+```bash
+clickup time create --task-id <id> --duration <ms> --start <ts>
+    [--description <text>] [--assignee <id>] [--billable <bool>] [--tag <name>...]
+
+clickup time update <timer-id> --workspace-id <id>
+    [--description <text>] [--duration <ms>] [--start <ts>]
+    [--tag-action <add|remove>] [--tag <name>...] [--billable <bool>]
+
+clickup time delete <timer-id> --workspace-id <id>
+```
+
+### Get / History
+```bash
+clickup time get <timer-id> --workspace-id <id>
+clickup time history <timer-id> --workspace-id <id>
+```
+
+## Running Timers
+
+```bash
+clickup time start --task-id <id> --workspace-id <id>
+    [--description <text>] [--billable <bool>] [--tag <name>...]
+clickup time stop --workspace-id <id>
+clickup time running --workspace-id <id> [--assignee <id>]
+```
+
+## Time Tags
+
+```bash
+clickup time tags --workspace-id <id>                              # List all time tags
+clickup time add-tags --workspace-id <id> --timer-id <id>... --tag <name>...
+clickup time remove-tags --workspace-id <id> --timer-id <id>... --tag <name>...
+clickup time rename-tag --workspace-id <id> --name <old> --new-name <new>
+```
+
+## Common Patterns
+
+```bash
+# Log 2 hours of billable work
+clickup time create --task-id abc9zt --duration 7200000 --start 1735650000000 --billable true
+
+# Start a timer, do work, then stop it
+clickup time start --task-id abc9zt --workspace-id 9876543 --description "API refactor"
+# ... work ...
+clickup time stop --workspace-id 9876543
+
+# Check who has timers running
+clickup time running --workspace-id 9876543
+
+# Get all time entries for this week
+clickup time list --workspace-id 9876543 --start 2025-01-06 --end 2025-01-12
+
+# Render time entries as markdown table for reports
+clickup time list --workspace-id 9876543 --format md
+```
+
+## Notes
+
+- Duration is always in **milliseconds** (1 hour = 3600000, 1 minute = 60000)
+- Start timestamps are Unix milliseconds
+- `time delete` does **not** require `--confirm` (unlike most delete commands)
+
+## Discovery
+
+```bash
+clickup schema time.create    # Show create fields
+clickup schema time.list      # Show list/filter options
+```

package/skills/clickup-time-audit/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: clickup-time-audit
+description: Audits time tracking entries by checking utilization, finding missing entries, and comparing logged vs. estimated time. Use when the user wants to audit time, check billable hours, find unlogged work, or review team utilization.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[workspace-id] [start-date] [end-date]"
+allowed-tools: Bash(clickup *)
+---
+
+# Time Audit
+
+Audit time tracking data for accuracy, utilization, and completeness.
+
+## Prerequisites
+
+- Workspace ID
+- Date range for the audit period
+
+## Workflow
+
+### Step 1: Pull all time entries for the period
+
+```bash
+clickup time list --workspace-id <id> \
+  --start <period-start-ms> --end <period-end-ms> \
+  --format json
+```
+
+### Step 2: Check per-person totals
+
+From the JSON output, group by assignee and sum durations:
+- Total hours per person
+- Expected hours (working days x hours per day)
+- Utilization % = logged / expected
+
+### Step 3: Find tasks with time but no entries
+
+```bash
+# Get tasks that were active in the period
+clickup task search --workspace-id <id> \
+  --date-updated-gt <period-start-ms> \
+  --date-updated-lt <period-end-ms> \
+  --status "in progress" --status "complete" \
+  --format json
+```
+
+Cross-reference: tasks that changed status but have zero time logged may be missing entries.
+
+### Step 4: Compare estimated vs. actual
+
+For tasks with time estimates:
+- Pull task data (has `time_estimate` field)
+- Pull time entries for those tasks
+- Compare: actual / estimated ratio
+
+```bash
+# Get a task with its time estimate
+clickup task get <task-id> --format json
+
+# Get time logged on that task
+clickup time list --task-id <task-id> --format json
+```
+
+### Step 5: Check for billable time
+
+Filter time entries by billable flag to calculate billable vs. non-billable split.
+
+### Step 6: Identify anomalies
+
+Look for:
+- Entries over 8 hours (forgot to stop timer?)
+- Entries with no description
+- Running timers that have been active for days
+
+```bash
+# Check for currently running timers
+clickup time running --workspace-id <id> --format json
+```
+
+## Tips
+
+- Duration is in milliseconds. Divide by 3600000 for hours.
+- Use time tags to categorize entries (e.g., "client-work", "internal", "overhead")
+- Run audits weekly to catch issues early rather than at month-end

package/skills/clickup-users/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: clickup-users
+description: Manages ClickUp workspace users, groups, guests, roles, and members. Use when the user asks about team members, wants to invite users, manage groups, grant guest access, check permissions, resolve names to IDs, or see who is assigned to what.
+allowed-tools: Bash(clickup user *), Bash(clickup group *), Bash(clickup guest *), Bash(clickup role *), Bash(clickup member *), Bash(clickup workspace members), Bash(clickup schema user*), Bash(clickup schema group*), Bash(clickup schema guest*), Bash(clickup schema member*)
+---
+
+# ClickUp Users and Access
+
+Manage workspace members, user groups, guest access, roles, and member lists.
+
+## User Commands
+
+```bash
+clickup user invite --workspace-id <id> --email <email> [--admin <bool>]
+clickup user get <user-id> --workspace-id <id>
+clickup user update <user-id> --workspace-id <id> [--username <name>] [--admin <bool>] [--custom-role-id <id>]
+clickup user remove <user-id> --workspace-id <id> --confirm
+```
+
+## Group Commands
+
+```bash
+clickup group list --workspace-id <id>
+clickup group create --workspace-id <id> --name <name> [--member-id <id>...]
+clickup group update <group-id> --workspace-id <id> [--name <name>] [--add-member <id>...] [--remove-member <id>...]
+clickup group delete <group-id> --workspace-id <id> --confirm
+```
+
+## Guest Commands
+
+Guests have scoped access (read, comment, edit, or create) per resource.
+
+```bash
+clickup guest invite --workspace-id <id> --email <email>
+    [--can-edit-tags <bool>] [--can-see-time-spent <bool>]
+clickup guest get <guest-id> --workspace-id <id>
+clickup guest update <guest-id> --workspace-id <id> [--username <name>]
+clickup guest remove <guest-id> --workspace-id <id> --confirm
+
+# Grant/revoke access to specific resources
+clickup guest add-to-task <guest-id> --task-id <id> --permission <read|comment|edit|create>
+clickup guest remove-from-task <guest-id> --task-id <id>
+clickup guest add-to-list <guest-id> --list-id <id> --permission <read|comment|edit|create>
+clickup guest remove-from-list <guest-id> --list-id <id>
+clickup guest add-to-folder <guest-id> --folder-id <id> --permission <read|comment|edit|create>
+clickup guest remove-from-folder <guest-id> --folder-id <id>
+```
+
+## Workspace Member Commands
+
+```bash
+# List all members in workspace (full directory)
+clickup workspace members --workspace-id <id>
+
+# Find a member by name (fuzzy match on username or email)
+clickup member find --name "Alice" --workspace-id <id>
+
+# Resolve names to user IDs (pipe-friendly)
+clickup member resolve --names "Alice, Bob" --workspace-id <id>
+
+# Get IDs only for use in other commands
+clickup member resolve --names "Alice, Bob" --format quiet
+```
+
+## Role and Member Commands
+
+```bash
+clickup role list --workspace-id <id>                  # List custom roles (Business plan)
+clickup member list --task-id <id>                     # List assignable users for a task
+clickup member list --list-id <id>                     # List assignable users for a list
+```
+
+## Common Patterns
+
+```bash
+# Invite a team member as admin
+clickup user invite --workspace-id 9876543 --email dev@company.com --admin true
+
+# Create a team group
+clickup group create --workspace-id 9876543 --name "Frontend Team" --member-id 112233 --member-id 445566
+
+# Give a client read access to a folder
+clickup guest invite --workspace-id 9876543 --email client@external.com
+clickup guest add-to-folder guest_001 --folder-id 998877 --permission read
+
+# Find a user ID from a name (common agent pattern)
+clickup member find --name "Sarah" --format json | jq '.[0].id'
+
+# Resolve multiple names to IDs for bulk assignment
+IDS=$(clickup member resolve --names "Alice, Bob, Carol" --format quiet | tr '\n' ',')
+clickup task update TASK_ID --assignee-add $IDS
+
+# Display workspace directory as markdown table
+clickup workspace members --format md
+```
+
+## Resolving Names to IDs
+
+Agents often receive person names but ClickUp APIs require user IDs. Use these commands to bridge the gap:
+
+```bash
+# 1. Find one person
+clickup member find --name "Alice Johnson" --format json
+
+# 2. Resolve multiple names at once (outputs table with id/username/email)
+clickup member resolve --names "Alice, Bob, Sarah"
+
+# 3. IDs-only output for piping into task assignee flags
+clickup member resolve --names "Alice, Bob" --format quiet
+# outputs:
+# 1234567
+# 8901234
+```
+
+## Discovery
+
+```bash
+clickup schema users.invite    # Show invite fields
+clickup schema guests.invite   # Show guest invite fields
+clickup schema member.find     # Show find flags
+clickup schema member.resolve  # Show resolve flags
+```

package/skills/clickup-views/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: clickup-views
+description: Creates and manages ClickUp views including board, list, Gantt, calendar, and workload views. Use when the user asks about views, wants to create a kanban board, see tasks through a specific view, or configure view settings.
+allowed-tools: Bash(clickup view *), Bash(clickup schema view*)
+---
+
+# ClickUp Views
+
+Views are saved display configurations that can exist at workspace, space, folder, or list level.
+
+## Commands
+
+### List views
+```bash
+clickup view list --workspace-id <id>
+clickup view list --space-id <id>
+clickup view list --folder-id <id>
+clickup view list --list-id <id>
+```
+
+### Get / Create / Update / Delete
+```bash
+clickup view get <view-id>
+
+clickup view create --workspace-id <id> --name <name> --type <type>
+clickup view create --space-id <id> --name <name> --type <type>
+clickup view create --folder-id <id> --name <name> --type <type>
+clickup view create --list-id <id> --name <name> --type <type>
+
+clickup view update <view-id> [--name <name>] [--settings <json>]
+    [--grouping <json>] [--sorting <json>] [--filters <json>]
+
+clickup view delete <view-id> --confirm
+```
+
+### Get tasks from a view
+```bash
+clickup view tasks <view-id> [--page <n>]
+```
+
+## View Types
+
+`list`, `board`, `calendar`, `gantt`, `table`, `timeline`, `activity`, `map`, `workload`
+
+## Common Patterns
+
+```bash
+# Create a kanban board at the space level
+clickup view create --space-id 55544433 --name "Sprint Board" --type board
+
+# Get all tasks visible in a view
+clickup view tasks view_abc --format json
+
+# List views at the workspace level
+clickup view list --workspace-id 9876543
+
+# Render view tasks as markdown table
+clickup view tasks view_abc --format md
+```
+
+## Discovery
+
+```bash
+clickup schema views.create    # Show create fields and view types
+```

package/skills/clickup-webhooks/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: clickup-webhooks
+description: Registers and manages ClickUp webhooks for real-time event notifications. Use when the user asks about webhooks, wants to set up notifications for task changes, or needs to integrate ClickUp events with external services.
+allowed-tools: Bash(clickup webhook *), Bash(clickup schema webhook*)
+---
+
+# ClickUp Webhooks
+
+Webhooks deliver real-time event payloads to your endpoint when activity occurs in ClickUp.
+
+## Commands
+
+```bash
+clickup webhook list --workspace-id <id>
+
+clickup webhook create --workspace-id <id> --endpoint <url> --events <event>...
+    [--space-id <id>] [--folder-id <id>] [--list-id <id>] [--task-id <id>]
+
+clickup webhook update <webhook-id>
+    [--endpoint <url>] [--events <event>...] [--status <active|inactive>]
+
+clickup webhook delete <webhook-id> --confirm
+
+clickup webhook events    # List all available event types
+```
+
+## Scoping
+
+Webhooks can be scoped to a specific resource level:
+- **Workspace-wide**: Omit scope flags (receives all events)
+- **Space**: Add `--space-id <id>`
+- **Folder**: Add `--folder-id <id>`
+- **List**: Add `--list-id <id>`
+- **Task**: Add `--task-id <id>`
+
+## Common Patterns
+
+```bash
+# List available event types
+clickup webhook events
+
+# Create a webhook for task events in a space
+clickup webhook create --workspace-id 9876543 --endpoint https://hooks.example.com/clickup \
+  --events taskCreated taskUpdated --space-id 55544433
+
+# Disable a webhook temporarily
+clickup webhook update wh_001 --status inactive
+
+# Re-enable it
+clickup webhook update wh_001 --status active
+
+# List webhooks as markdown table
+clickup webhook list --workspace-id 9876543 --format md
+```
+
+## Discovery
+
+```bash
+clickup schema webhooks.create    # Show webhook create fields
+clickup webhook events            # List all event type names
+```