clickup-agent-cli 0.2.0

package/skills/clickup-goal-progress/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: clickup-goal-progress
+description: Reports on goal and OKR completion status by tracking key results, identifying at-risk goals, and updating progress. Use when the user asks about goal progress, OKR status, quarterly objectives, or wants to check if targets are on track.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[workspace-id]"
+allowed-tools: Bash(clickup *)
+---
+
+# Goal Progress Report
+
+Track OKR/goal completion, update key results, and identify goals that are at risk.
+
+## Prerequisites
+
+- Workspace ID
+
+## Workflow
+
+### Step 1: List all active goals
+
+```bash
+clickup goal list --workspace-id <id> --format json
+```
+
+### Step 2: Get detailed progress for each goal
+
+```bash
+clickup goal get <goal-id> --format json
+```
+
+The response includes key results with current progress values.
+
+### Step 3: Calculate goal health
+
+For each goal, assess:
+- **On track**: Key results trending toward target by due date
+- **At risk**: Key results below expected progress for the timeline
+- **Behind**: Key results significantly below expected pace
+
+Formula: Expected progress = (days elapsed / total days) * target value
+
+### Step 4: Update key result progress
+
+```bash
+# Update a numeric key result
+clickup goal update-key-result <kr-id> --steps-current 75 --note "Completed batch import feature"
+
+# For automatic key results, check linked list/task completion
+clickup task list --list-id <linked-list-id> --include-closed --format json
+```
+
+### Step 5: Compile the report
+
+For each goal:
+- **Goal name** and due date
+- **Key results**: Current vs. target, % complete
+- **Status**: On track / At risk / Behind
+- **Notes**: Latest updates on each key result
+
+### Step 6: Post updates (optional)
+
+```bash
+# Add a progress note to a key result
+clickup goal update-key-result <kr-id> --note "Sprint 11 pushed this to 80%. On track for Q1 target."
+```
+
+## Tips
+
+- Run goal progress reports weekly or bi-weekly
+- Automatic key results linked to lists update in real-time as tasks are completed
+- For manual key results (number, percentage), update `--steps-current` regularly
+- Goals with no recent key result updates are likely stale and need attention

package/skills/clickup-goals/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: clickup-goals
+description: Creates and manages ClickUp goals with measurable key results for OKR tracking. Use when the user asks about goals, OKRs, key results, objectives, progress tracking, or wants to set targets and measure completion.
+allowed-tools: Bash(clickup goal *), Bash(clickup schema goal*)
+---
+
+# ClickUp Goals
+
+Goals track high-level objectives with measurable key results. Key results can be numeric, currency, boolean, percentage, or derived from linked tasks.
+
+## Goal Commands
+
+```bash
+clickup goal list --workspace-id <id> [--include-completed]
+clickup goal get <goal-id>
+clickup goal create --workspace-id <id> --name <name>
+    [--due-date <ts>] [--description <text>] [--multiple-owners <bool>]
+    [--owner <id>...] [--color <hex>]
+clickup goal update <goal-id> [--name <name>] [--due-date <ts>] [--description <text>] [--color <hex>]
+clickup goal delete <goal-id> --confirm
+```
+
+## Key Result Commands
+
+```bash
+clickup goal add-key-result <goal-id> --name <name> --type <type>
+    [--steps-start <n>] [--steps-end <n>] [--unit <s>]
+    [--task-ids <id>...] [--list-ids <id>...]
+
+clickup goal update-key-result <key-result-id>
+    [--name <name>] [--steps-current <n>] [--note <text>]
+
+clickup goal delete-key-result <key-result-id> --confirm
+```
+
+Key result types: `number`, `currency`, `boolean`, `percentage`, `automatic`
+
+- `automatic` type tracks completion % from linked tasks or lists
+- Use `--task-ids` or `--list-ids` with automatic type
+
+## Common Patterns
+
+```bash
+# Create a quarterly goal
+clickup goal create --workspace-id 9876543 --name "Launch v2.0" \
+  --due-date 1740787200000 --owner 112233
+
+# Add a percentage key result
+clickup goal add-key-result goal_001 --name "Test coverage" \
+  --type percentage --steps-start 60 --steps-end 90
+
+# Track sprint progress automatically
+clickup goal add-key-result goal_001 --name "Sprint tasks" \
+  --type automatic --list-ids 998877
+
+# Update progress on a numeric key result
+clickup goal update-key-result kr_001 --steps-current 75 --note "On track"
+
+# List all active goals
+clickup goal list --workspace-id 9876543
+
+# Render goals as markdown table
+clickup goal list --workspace-id 9876543 --format md
+```
+
+## Discovery
+
+```bash
+clickup schema goals.create           # Show goal create fields
+clickup schema goals.add-key-result   # Show key result fields
+```

package/skills/clickup-project-setup/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: clickup-project-setup
+description: Scaffolds a new project in ClickUp by creating a space, folders, lists, tags, and initial tasks. Use when the user wants to set up a new project, create a project structure, or bootstrap a workspace for a new initiative.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[workspace-id] [project-name]"
+allowed-tools: Bash(clickup *)
+---
+
+# Project Setup
+
+Create a complete project structure in ClickUp from scratch.
+
+## Prerequisites
+
+- Workspace ID
+- Project name and structure plan
+
+## Workflow
+
+### Step 1: Create the space
+
+```bash
+SPACE=$(clickup space create --workspace-id <id> --name "Project Alpha" \
+  --features '{"due_dates":{"enabled":true},"time_tracking":{"enabled":true},"tags":{"enabled":true}}' \
+  --format id)
+```
+
+### Step 2: Create folders for work streams
+
+```bash
+DESIGN=$(clickup folder create --space-id $SPACE --name "Design" --format id)
+ENGINEERING=$(clickup folder create --space-id $SPACE --name "Engineering" --format id)
+QA=$(clickup folder create --space-id $SPACE --name "QA" --format id)
+```
+
+### Step 3: Create lists within folders
+
+```bash
+# Engineering lists
+clickup list create --folder-id $ENGINEERING --name "Backlog"
+clickup list create --folder-id $ENGINEERING --name "Sprint 1"
+clickup list create --folder-id $ENGINEERING --name "Tech Debt"
+
+# Design lists
+clickup list create --folder-id $DESIGN --name "Design Backlog"
+clickup list create --folder-id $DESIGN --name "In Progress"
+
+# QA lists
+clickup list create --folder-id $QA --name "Test Cases"
+clickup list create --folder-id $QA --name "Bug Reports"
+```
+
+### Step 4: Create folderless lists (optional)
+
+```bash
+# Top-level project docs/notes list
+clickup list create-folderless --space-id $SPACE --name "Project Notes"
+```
+
+### Step 5: Create tags
+
+```bash
+clickup tag create --space-id $SPACE --name "mvp" --bg-color "#22C55E"
+clickup tag create --space-id $SPACE --name "tech-debt" --bg-color "#F59E0B"
+clickup tag create --space-id $SPACE --name "blocked" --bg-color "#EF4444"
+clickup tag create --space-id $SPACE --name "design-review" --bg-color "#8B5CF6"
+```
+
+### Step 6: Create initial milestone tasks
+
+```bash
+BACKLOG=$(clickup list list --folder-id $ENGINEERING --format json | # extract backlog list ID)
+
+clickup task create --list-id $BACKLOG --name "Project kickoff" --priority 1
+clickup task create --list-id $BACKLOG --name "Architecture design" --priority 2
+clickup task create --list-id $BACKLOG --name "MVP feature set defined" --priority 2
+clickup task create --list-id $BACKLOG --name "First sprint planning" --priority 2
+```
+
+### Step 7: Create a project goal (optional)
+
+```bash
+clickup goal create --workspace-id <id> --name "Project Alpha - MVP Launch" \
+  --due-date <target-date-ms> --color "#3B82F6"
+```
+
+### Step 8: Set up a webhook for notifications (optional)
+
+```bash
+clickup webhook create --workspace-id <id> \
+  --endpoint https://hooks.example.com/project-alpha \
+  --events taskCreated taskUpdated taskDeleted \
+  --space-id $SPACE
+```
+
+## Tips
+
+- Capture list IDs from create commands using `--format id` for later use
+- Enable features on the space at creation time to avoid updating later
+- Use consistent tag colors across projects for visual consistency

package/skills/clickup-spaces/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: clickup-spaces
+description: Navigates and manages the ClickUp hierarchy including workspaces, spaces, folders, and lists. Use when the user asks about project structure, wants to create spaces or lists, navigate the hierarchy, or find where tasks live.
+allowed-tools: Bash(clickup workspace *), Bash(clickup space *), Bash(clickup folder *), Bash(clickup list *), Bash(clickup schema workspace*), Bash(clickup schema space*), Bash(clickup schema folder*), Bash(clickup schema list*)
+---
+
+# ClickUp Spaces (Hierarchy)
+
+Manage the organizational hierarchy: Workspace > Space > Folder > List. Lists contain tasks.
+
+## Workspace Commands
+
+```bash
+clickup workspace list                          # List all workspaces
+clickup workspace get [--workspace-id <id>]     # Get workspace details
+clickup workspace seats [--workspace-id <id>]   # Show seat usage
+clickup workspace plan [--workspace-id <id>]    # Show billing plan
+```
+
+## Space Commands
+
+```bash
+clickup space list [--workspace-id <id>] [--archived]
+clickup space get <space-id>
+clickup space create --workspace-id <id> --name <name> [--multiple-assignees] [--features <json>]
+clickup space update <space-id> [--name <name>] [--color <hex>] [--private <bool>]
+clickup space delete <space-id> --confirm
+```
+
+## Folder Commands
+
+```bash
+clickup folder list --space-id <id> [--archived]
+clickup folder get <folder-id>
+clickup folder create --space-id <id> --name <name>
+clickup folder update <folder-id> [--name <name>]
+clickup folder delete <folder-id> --confirm
+```
+
+## List Commands
+
+```bash
+clickup list list --folder-id <id> [--archived]           # Lists in a folder
+clickup list list-folderless --space-id <id> [--archived]  # Lists directly in a space
+clickup list get <list-id>
+clickup list create --folder-id <id> --name <name> [--content <text>] [--due-date <ts>] [--priority <1-4>]
+clickup list create-folderless --space-id <id> --name <name> [--content <text>]
+clickup list update <list-id> [--name <name>] [--content <text>]
+clickup list delete <list-id> --confirm
+clickup list add-task <list-id> --task-id <id>
+clickup list remove-task <list-id> --task-id <id>
+```
+
+## Common Patterns
+
+```bash
+# Navigate the full hierarchy
+clickup workspace list
+clickup space list --workspace-id <id>
+clickup folder list --space-id <id>
+clickup list list --folder-id <id>
+clickup task list --list-id <id>
+
+# Find a list by exploring
+clickup space list | grep "Engineering"
+clickup folder list --space-id <id> | grep "Sprint"
+
+# Set default workspace to avoid repeating --workspace-id
+clickup config set workspace_id <id>
+
+# Render folder list as markdown table for display in docs or chat
+clickup folder list --space-id <id> --format md
+```
+
+## Key Concepts
+
+- **Workspace** (also called "team"): Top-level container. Most users have one.
+- **Space**: Primary organizational unit within a workspace. Has its own settings and features.
+- **Folder**: Optional grouping inside a space. Contains lists.
+- **List**: Contains tasks. Can be inside a folder or directly in a space (folderless).
+- A task can belong to multiple lists.
+
+## Discovery
+
+```bash
+clickup schema spaces         # List space actions
+clickup schema lists.create   # Show list create fields
+```

package/skills/clickup-sprint-closeout/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: clickup-sprint-closeout
+description: Closes out a sprint by summarizing completion, carrying over incomplete tasks, and preparing retrospective data. Use when the user wants to end a sprint, close out an iteration, move unfinished work, or prepare for a retro.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[sprint-list-id] [next-sprint-list-id]"
+allowed-tools: Bash(clickup *)
+---
+
+# Sprint Closeout
+
+End a sprint cleanly: summarize what was done, carry over incomplete work, and gather data for a retrospective.
+
+## Prerequisites
+
+- Sprint list ID
+- Next sprint list ID (or create one)
+- Workspace ID
+
+## Workflow
+
+### Step 1: Get sprint completion status
+
+```bash
+# All tasks in the sprint list
+clickup task list --list-id <sprint-list-id> --include-closed --format json
+```
+
+Categorize: completed vs. incomplete.
+
+### Step 2: Calculate metrics
+
+From the JSON output, compute:
+- Total tasks in sprint
+- Completed count
+- Incomplete count
+- Completion percentage
+
+```bash
+# Get time logged during the sprint
+clickup time list --workspace-id <id> \
+  --start <sprint-start-ms> --end <sprint-end-ms> \
+  --format json
+```
+
+### Step 3: Carry over incomplete tasks
+
+```bash
+# Move incomplete tasks to the next sprint
+clickup list add-task <next-sprint-list-id> --task-id <incomplete-task-1>
+clickup list add-task <next-sprint-list-id> --task-id <incomplete-task-2>
+
+# Update their dates to the new sprint window
+clickup task update <incomplete-task-1> \
+  --start-date <new-sprint-start-ms> \
+  --due-date <new-sprint-end-ms>
+```
+
+### Step 4: Update goal progress (if sprint had a goal)
+
+```bash
+clickup goal get <sprint-goal-id> --format json
+```
+
+If using automatic key results linked to the sprint list, progress updates automatically.
+
+### Step 5: Gather retro data
+
+Compile for the retrospective:
+- **Completed**: List of finished tasks
+- **Carried over**: Tasks that did not finish and why
+- **Time analysis**: Total hours logged vs. estimated
+- **Blockers encountered**: Tasks that were blocked and for how long
+
+```bash
+# Time-in-status for carried-over tasks (shows where time was spent)
+clickup task bulk-time-in-status --task-id <id1> --task-id <id2> --format json
+```
+
+### Step 6: Post summary (optional)
+
+```bash
+clickup comment create --task-id <retro-task-id> --text "Sprint 11 closeout: 85% completion (17/20 tasks). 3 carried over. See details below."
+```
+
+## Tips
+
+- Always `--include-closed` when listing sprint tasks to see the full picture
+- Use `time-in-status` to identify bottlenecks (tasks stuck in review, etc.)
+- Tag carried-over tasks so they are easy to identify in the next sprint

package/skills/clickup-sprint-planning/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: clickup-sprint-planning
+description: Plans a sprint by selecting tasks from backlog, assigning them, setting dates, and organizing into a sprint list. Use when the user wants to plan a sprint, set up an iteration, or pull work from backlog into a sprint.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[backlog-list-id] [sprint-name]"
+allowed-tools: Bash(clickup *)
+---
+
+# Sprint Planning
+
+Set up a new sprint by pulling tasks from the backlog, estimating, assigning, and organizing.
+
+## Prerequisites
+
+- Workspace and space IDs known
+- Backlog list ID where unplanned tasks live
+- Sprint list exists (or create one)
+
+## Workflow
+
+### Step 1: Create the sprint list (if needed)
+
+```bash
+SPRINT_LIST=$(clickup list create --folder-id <folder-id> --name "Sprint 12 (Mar 10-21)" --format id)
+```
+
+Or for folderless:
+```bash
+SPRINT_LIST=$(clickup list create-folderless --space-id <space-id> --name "Sprint 12" --format id)
+```
+
+### Step 2: Review the backlog
+
+```bash
+# List unassigned or unprioritized tasks in backlog
+clickup task list --list-id <backlog-list-id> --format json
+
+# Or search for high-priority items
+clickup task search --workspace-id <id> --priority 1 --priority 2 \
+  --status "backlog" --status "to do" --format json
+```
+
+### Step 3: Move tasks into the sprint
+
+```bash
+# Add selected tasks to the sprint list
+clickup list add-task $SPRINT_LIST --task-id <task-id-1>
+clickup list add-task $SPRINT_LIST --task-id <task-id-2>
+clickup list add-task $SPRINT_LIST --task-id <task-id-3>
+```
+
+### Step 4: Assign and set dates
+
+```bash
+# Update each task with assignee, dates, and estimate
+clickup task update <task-id> \
+  --assignee-add 112233 \
+  --start-date <sprint-start-ms> \
+  --due-date <sprint-end-ms> \
+  --status "to do"
+```
+
+### Step 5: Set time estimates (optional)
+
+```bash
+clickup task update <task-id> --time-estimate 14400000   # 4 hours
+```
+
+### Step 6: Create a sprint goal (optional)
+
+```bash
+GOAL=$(clickup goal create --workspace-id <id> --name "Sprint 12 - Ship auth module" \
+  --due-date <sprint-end-ms> --format id)
+
+# Link the sprint list as an automatic key result
+clickup goal add-key-result $GOAL --name "Sprint tasks completed" \
+  --type automatic --list-ids $SPRINT_LIST
+```
+
+### Step 7: Verify sprint setup
+
+```bash
+# List all tasks in the new sprint
+clickup task list --list-id $SPRINT_LIST --format table
+```
+
+## Tips
+
+- Tasks can belong to multiple lists, so adding to a sprint list does not remove from backlog
+- Use `--format quiet` to get just IDs for scripting
+- Set the sprint goal with `--type automatic` to auto-track % completion
+- Consider tagging sprint tasks: `clickup tag add --task-id <id> --name "sprint-12"`

package/skills/clickup-standup/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: clickup-standup
+description: Generates a daily standup summary from ClickUp covering what was done yesterday, what is planned today, and blockers. Use when the user asks for a standup report, daily update, or wants to know what they or their team worked on.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[scope - e.g. 'my tasks', 'engineering team', user-id]"
+allowed-tools: Bash(clickup *)
+---
+
+# Daily Standup
+
+Generate a standup report covering yesterday's progress, today's plan, and current blockers.
+
+## Understanding the Scope
+
+Interpret `$ARGUMENTS` to determine who the standup is for:
+
+- **"my tasks"** or no arguments: Use the authenticated user
+- **A person's name**: Find their user ID via `clickup user list` or `clickup member list`
+- **A team/space name**: Get all members of that space and generate a team standup
+- **A user ID**: Use directly
+
+## Workflow
+
+### Step 1: What was done yesterday
+
+```bash
+# Tasks updated yesterday with completed/closed status
+clickup task search --workspace-id <id> \
+  --date-updated-gt <yesterday-start-ms> \
+  --date-updated-lt <yesterday-end-ms> \
+  --assignee <user-id> \
+  --status "complete" --status "closed" --status "done" \
+  --format json
+```
+
+### Step 2: What is in progress today
+
+```bash
+clickup task search --workspace-id <id> \
+  --assignee <user-id> \
+  --status "in progress" --status "in review" \
+  --format json
+```
+
+### Step 3: What is due today or overdue
+
+```bash
+clickup task search --workspace-id <id> \
+  --assignee <user-id> \
+  --due-date-lt <end-of-today-ms> \
+  --include-closed false \
+  --format json
+```
+
+### Step 4: Check for blockers
+
+Look for tasks with dependencies or "blocked" status:
+
+```bash
+clickup task search --workspace-id <id> \
+  --assignee <user-id> \
+  --status "blocked" --status "waiting" \
+  --format json
+```
+
+### Step 5: Check running timer (optional)
+
+```bash
+clickup time running --workspace-id <id> --assignee <user-id> --format json
+```
+
+### Step 6: Compile standup
+
+Format as:
+
+```
+**Yesterday:**
+- Completed: [list of finished tasks with names]
+
+**Today:**
+- Working on: [list of in-progress tasks]
+- Due today: [list of tasks due today]
+
+**Blockers:**
+- [list of blocked tasks, if any]
+```
+
+## Tips
+
+- Adjust timestamps: yesterday = midnight to midnight in the team's timezone
+- For team standups, loop through multiple `--assignee` values
+- Post the standup summary as a comment on a recurring "standup" task if desired

package/skills/clickup-task-triage/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: clickup-task-triage
+description: Triages incoming ClickUp tasks by categorizing, prioritizing, assigning, and routing unprocessed tasks. Use when the user wants to triage tasks, sort through a backlog, prioritize incoming work, or clean up an inbox list.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[inbox-list-id]"
+allowed-tools: Bash(clickup *)
+---
+
+# Task Triage
+
+Sort through incoming/unprocessed tasks: prioritize, assign, add tags, and move to the right lists.
+
+## Prerequisites
+
+- Know the inbox/backlog list ID where new tasks land
+- Know space IDs and assignee user IDs
+
+## Workflow
+
+### Step 1: Get unprocessed tasks
+
+```bash
+# List tasks with no priority or assignee (likely untriaged)
+clickup task list --list-id <inbox-list-id> --format json
+```
+
+Filter candidates: tasks with priority=null, no assignees, or status "new"/"backlog".
+
+### Step 2: Categorize each task
+
+For each task, determine:
+- **Priority**: 1 (urgent), 2 (high), 3 (normal), 4 (low)
+- **Assignee**: Who should own it
+- **Tags**: Bug, feature, improvement, support, etc.
+
+### Step 3: Update tasks
+
+```bash
+# Set priority and assign
+clickup task update <task-id> --priority 2 --assignee-add 112233 --status "to do"
+
+# Add categorization tags
+clickup tag add --task-id <task-id> --name "bug"
+
+# Set a due date if time-sensitive
+clickup task update <task-id> --due-date <timestamp-ms>
+```
+
+### Step 4: Route to appropriate lists (optional)
+
+```bash
+# Move bug to the bugs list
+clickup list add-task <bugs-list-id> --task-id <task-id>
+
+# Move feature request to the feature backlog
+clickup list add-task <features-list-id> --task-id <task-id>
+```
+
+### Step 5: Handle duplicates
+
+```bash
+# Search for similar tasks
+clickup task search --workspace-id <id> --query "error in login page"
+
+# If duplicate found, add a dependency or comment
+clickup comment create --task-id <task-id> --text "Duplicate of <other-task-id>. Closing."
+clickup task update <task-id> --status "closed"
+```
+
+### Step 6: Verify triage is complete
+
+```bash
+# Confirm no tasks remain unprocessed
+clickup task list --list-id <inbox-list-id> --status "new" --format quiet
+```
+
+## Tips
+
+- Triage regularly (daily or per-sprint) to prevent backlog buildup
+- Use `clickup task search --query` to detect duplicates before assigning
+- Batch operations: pipe task IDs for efficiency
+  ```bash
+  clickup task list --list-id <id> --format quiet | xargs -I{} clickup task update {} --priority 3
+  ```