clickup-agent-cli 0.4.2 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -10,8 +10,8 @@
     {
       "name": "clickup",
       "source": "./",
-      "description": "ClickUp CLI with 25 agent skills covering the full API -- token-efficient alternative to MCP with chat, time tracking, docs, and project management workflows",
-      "version": "0.4.2",
+      "description": "ClickUp CLI with 31 agent skills covering the full API -- token-efficient alternative to MCP with chat, time tracking, docs, and project management workflows",
+      "version": "0.5.0",
       "homepage": "https://github.com/henryreith/clickup-cli",
       "keywords": ["clickup", "project-management", "tasks", "time-tracking"],
       "category": "productivity"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "clickup",
-  "description": "ClickUp CLI with 25 agent skills covering the full API -- token-efficient alternative to MCP with chat, time tracking, docs, and project management workflows",
-  "version": "0.4.2",
+  "description": "ClickUp CLI with 31 agent skills covering the full API -- token-efficient alternative to MCP with chat, time tracking, docs, and project management workflows",
+  "version": "0.5.0",
   "author": {
     "name": "Henry Reith"
   },

package/README.md

@@ -80,7 +80,7 @@ Every command supports multiple output formats:
 
 ## AI Agent Usage
 
-The CLI is built from the ground up for AI agents, following the "CLI as execution layer, skills as guidance layer" pattern. It ships as a Claude Code plugin with 25 agent skills, and works with any agent platform that can run bash commands.
+The CLI is built from the ground up for AI agents, following the "CLI as execution layer, skills as guidance layer" pattern. It ships as a Claude Code plugin with 31 agent skills, and works with any agent platform that can run bash commands.
 
 **vs ClickUp MCP:** This CLI covers the same operations as the official ClickUp MCP server (tasks, docs, time tracking, chat, members, hierarchy) plus more, while consuming far fewer tokens. A full skills hierarchy loads in ~150 tokens at session start vs injecting an entire API schema. Works in any agent platform that supports bash -- not just MCP-compatible hosts.
 
@@ -100,7 +100,7 @@ Install the ClickUp CLI as a Claude Code plugin for zero-friction access to all
 /clickup:sprint-planning list-id-here
 ```
 
-Once installed, Claude Code auto-discovers all 25 skills and loads them on demand. Recipe skills like `/clickup:weekly-review` run in isolated subagents with full ClickUp CLI access.
+Once installed, Claude Code auto-discovers all 31 skills and loads them on demand. Recipe skills like `/clickup:weekly-review` run in isolated subagents with full ClickUp CLI access.
 
 ### Claude Agent SDK
 
@@ -141,8 +141,8 @@ clickup skill show clickup-weekly-review
 
 **Three skill tiers:**
 - **Root skill** - Index and router. What the CLI does, how to discover more.
-- **Sub-skills** (11) - Per-resource command reference. Tasks, spaces, comments, time tracking, chat, etc.
-- **Recipe skills** (13) - Multi-step workflow guides that accept natural language arguments. Scope any recipe to a specific team, department, or person.
+- **Sub-skills** (12) - Per-resource command reference. Tasks, spaces, comments, time tracking, chat, etc.
+- **Recipe skills** (18) - Multi-step workflow guides that accept natural language arguments. Scope any recipe to a specific team, department, or person.
 
 **Example recipe invocations:**
 ```bash
@@ -201,7 +201,7 @@ clickup config validate
 
 # 4. Discover capabilities: the root skill indexes everything
 clickup skill show clickup          # start here (~150 tokens)
-clickup skill list                  # all 25 skills
+clickup skill list                  # all 31 skills
 clickup skill show clickup-tasks    # per-resource command reference
 
 # 5. Discover exact fields before calling a command

package/dist/clickup.js

@@ -4629,7 +4629,7 @@ function registerChatCommands(program, getClient) {
 }
 
 // src/cli.ts
-var VERSION = "0.4.2";
+var VERSION = "0.5.0";
 function createProgram() {
   const program = new Command();
   program.name("clickup").description("ClickUp CLI - Manage ClickUp workspaces from the terminal").version(VERSION).option("--token <token>", "API token").option("--token-file <path>", "Read API token from this file path").option("--profile <name>", "Profile to use (key, workspace name, or nickname)").option("--workspace-id <id>", "Workspace ID").addOption(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clickup-agent-cli",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "CLI covering the entire ClickUp API v2 surface",
   "type": "module",
   "bin": {
@@ -19,7 +19,8 @@
     "dev": "tsx bin/clickup.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "version": "node scripts/sync-version.js"
+    "version": "node scripts/sync-version.js",
+    "lint:skills": "node scripts/lint-skills.mjs"
   },
   "keywords": [
     "clickup",

package/skills/clickup/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clickup
 description: Manages ClickUp projects, tasks, spaces, lists, time tracking, goals, and more via CLI. Use when the user needs to create tasks, check project status, manage sprints, track time, find work items, or interact with ClickUp data in any way.
+license: MIT
 user-invocable: false
 ---
 
@@ -34,6 +35,8 @@ clickup skill list                     # All available skills
 clickup skill show <name>              # Print a skill's full contents (e.g. clickup-tasks)
 ```
 
+Known pitfalls (rate limits, error codes, exit codes, destructive-command rules) live in `references/gotchas.md` next to this file; read it before debugging a failing command (`clickup skill path clickup` prints this skill's directory).
+
 ## Sub-Skills (load when needed)
 
 | Skill | What it covers |
@@ -49,6 +52,7 @@ clickup skill show <name>              # Print a skill's full contents (e.g. cli
 | `clickup-webhooks` | Webhook registration and management |
 | `clickup-fields` | Custom fields, tags, custom task types |
 | `clickup-templates` | Templates: list available templates, apply task/list/folder templates |
+| `clickup-docs` | Docs and pages: create docs, write markdown pages, search the doc library |
 
 ## Recipe Skills (multi-step workflows)
 
@@ -69,6 +73,11 @@ Recipes accept natural language arguments. Scope them to any team, department, p
 | `clickup-capacity-check` | Check team workload and availability |
 | `clickup-blocker-report` | Find blocked tasks and dependency chains |
 | `clickup-goal-progress` | Report on goal/OKR completion |
+| `clickup-meeting-notes-to-tasks` | Turn meeting notes or transcripts into triaged tasks |
+| `clickup-workspace-audit` | Hygiene sweep: unassigned, overdue, stale, overloaded |
+| `clickup-timesheet-export` | Export time entries as a timesheet with totals |
+| `clickup-release-notes` | Changelog from completed tasks for a period |
+| `clickup-my-day` | Personal daily agenda ordered by what to tackle first |
 
 ## Quick Patterns
 

package/skills/clickup/references/gotchas.md

@@ -0,0 +1,57 @@
+# ClickUp CLI Gotchas
+
+Hard-won facts that prevent wasted retries. Read this when a command fails unexpectedly.
+
+## Exit codes
+
+| Code | Meaning | What to do |
+|------|---------|-----------|
+| 0 | Success | - |
+| 1 | General/API error | Read stderr; check `--debug` output |
+| 2 | Invalid arguments | Fix the flag value; the error names the flag |
+| 3 | Auth failure | Token missing/invalid: `clickup auth login` or set `CLICKUP_API_TOKEN` |
+| 4 | Not found | Wrong ID, or the token lacks access to that resource |
+| 5 | Permission denied | The token's user lacks access in ClickUp |
+| 6 | Rate limited | Already retried automatically; back off before batch work |
+| 7 | Network error | Timeout or connectivity; retry once, then report |
+
+## Rate limits
+
+- ClickUp allows ~100 requests/minute per token. The client retries 429s automatically, waiting for the reset window (capped at 60s).
+- For bulk work prefer the built-in bulk commands (`task bulk-update`, `task bulk-delete`); they run 3-wide concurrency deliberately.
+- Piping hundreds of IDs through `xargs` will hit the limit; batch in groups and expect pauses.
+
+## Destructive commands
+
+- Every true delete (and `field remove`, `time delete`) prompts in a terminal and requires `--confirm` when non-interactive. Agents must pass `--confirm` explicitly; never work around a missing confirmation.
+- Reversible link removals (`tag remove`, `relation remove`, `dependency remove`, `guest remove-from-*`, `list remove-task`) do not prompt.
+- `attachment download` refuses to overwrite an existing file without `--force`.
+
+## Common error codes (ECODE)
+
+| ECODE | Meaning |
+|-------|---------|
+| OAUTH_023 | Token invalid or expired: re-authenticate |
+| OAUTH_024 | Token lacks permission for this action |
+| ITEM_015 | Task not found: check the task ID |
+| TEAM_015 | Workspace not found: check workspace ID or `clickup config set workspace_id <id>` |
+
+## Input formats
+
+- Dates accept Unix ms, Unix seconds (10 digits), ISO 8601 (`2026-07-10`), and relative forms (`today`, `tomorrow`, `3d`, `-1w`, `friday`, `next monday`). Filter flags ending in `-gt`/`-lt` take Unix ms only.
+- Durations (time tracking) are milliseconds. 1h = 3600000.
+- `--priority` accepts 1-4 or urgent/high/normal/low.
+- Booleans passed as values (`--billable`, `--archived`) must be literal `true` or `false`.
+- JSON field names in output match the ClickUp API exactly; there is no camelCase conversion.
+
+## Output behavior
+
+- Piped output defaults to JSON; interactive terminals get tables. Force with `--format`.
+- `--format id` prints only the first result's ID: ideal for capture (`ID=$(clickup task create ... --format id)`).
+- Status messages and spinners go to stderr; stdout carries only data.
+- `skill show <name>` piped returns JSON with the skill body in the `content` field.
+
+## Workspace resolution
+
+- Most commands need a workspace ID. Resolution order: `--workspace-id` flag > `CLICKUP_WORKSPACE_ID` env > active profile > single-workspace auto-select.
+- After login, `clickup workspace setup` stores it; `clickup config validate` shows what is active.

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

@@ -1,6 +1,7 @@
 ---
 name: clickup-blocker-report
 description: Finds blocked tasks, dependency chains, and stale items that need attention. Use when the user asks about blockers, stuck tasks, stalled work, dependency issues, or wants to find what is holding up progress.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose
@@ -12,6 +13,8 @@ allowed-tools: Bash(clickup *)
 
 Identify blocked tasks, broken dependency chains, and items that have been stalled.
 
+Interpret `$ARGUMENTS` as the scope (workspace, space, list, person, or time period as the sections below expect); when it is empty, ask or fall back to the configured workspace.
+
 ## Prerequisites
 
 - Workspace ID

package/skills/clickup-capacity-check/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clickup-capacity-check
 description: Checks team workload and capacity by analyzing who is overloaded, who has bandwidth, and suggesting rebalancing. Use when the user asks about team capacity, workload, who is overloaded, or wants to balance task assignments.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose
@@ -12,6 +13,8 @@ allowed-tools: Bash(clickup *)
 
 Assess team workload by analyzing task assignments, time estimates, and time logged.
 
+Interpret `$ARGUMENTS` as the scope (workspace, space, list, person, or time period as the sections below expect); when it is empty, ask or fall back to the configured workspace.
+
 ## Prerequisites
 
 - Workspace ID

package/skills/clickup-chat/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clickup-chat
 description: Lists ClickUp chat channels and sends messages. Use when the user wants to post a notification, send a standup summary, notify a channel, or check what chat channels exist in the workspace.
+license: MIT
 allowed-tools: Bash(clickup chat *), Bash(clickup schema chat*)
 ---
 

package/skills/clickup-comments/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clickup-comments
 description: Creates, lists, and manages comments on ClickUp tasks, lists, and views. Supports threading and replies. Use when the user wants to add comments, read discussion threads, reply to comments, or assign action items via comments.
+license: MIT
 allowed-tools: Bash(clickup comment *), Bash(clickup schema comment*)
 ---
 

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

@@ -1,6 +1,7 @@
 ---
 name: clickup-custom-report
 description: Generates a custom ClickUp report based on any criteria the user describes. Handles ad-hoc queries like "show me all high-priority tasks assigned to John", "what's overdue in the backend", or "tasks created this month with no assignee". Use when the user asks for a specific data pull, custom query, filtered view, or any report that does not match a predefined recipe.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose

package/skills/clickup-docs/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: clickup-docs
+description: Manages ClickUp Docs and their pages including creating docs, writing page content in markdown, and searching doc libraries. Use when the user asks to create or update a doc, add meeting notes or documentation pages, read a doc's contents, or find a doc in the workspace.
+license: MIT
+allowed-tools: Bash(clickup doc *), Bash(clickup schema doc*)
+---
+
+# ClickUp Docs
+
+Create, read, update, and search Docs and their pages. All doc commands require a workspace ID (from `--workspace-id`, `CLICKUP_WORKSPACE_ID`, or the active profile).
+
+## Doc Commands
+
+```bash
+clickup doc list --workspace-id <id>
+clickup doc search --workspace-id <id> --query <text>
+clickup doc get --workspace-id <id> --doc-id <id>
+clickup doc create --workspace-id <id> --name <name>
+    [--parent-id <id>] [--parent-type <4|5|6|7>] [--visibility <private|workspace>]
+clickup doc update --workspace-id <id> --doc-id <id> --name <name>
+clickup doc delete --workspace-id <id> --doc-id <id> --confirm
+```
+
+`--parent-type` values: 4=space, 5=folder, 6=list, 7=task. When `--parent-id` is given without `--parent-type`, space (4) is assumed.
+
+## Page Commands
+
+Docs contain pages; page content is markdown.
+
+```bash
+clickup doc pages --workspace-id <id> --doc-id <id>
+clickup doc page-get --workspace-id <id> --doc-id <id> --page-id <id>
+clickup doc page-create --workspace-id <id> --doc-id <id> --name <name>
+    [--content <markdown>] [--parent-page-id <id>]
+clickup doc page-update --workspace-id <id> --doc-id <id> --page-id <id>
+    [--name <name>] [--content <markdown>]
+```
+
+## Common Patterns
+
+```bash
+# Find a doc by name, then read its pages
+DOC_ID=$(clickup doc search --query "Engineering Handbook" --format id)
+clickup doc pages --doc-id "$DOC_ID" --format json
+
+# Create a doc in a space with a first page
+DOC_ID=$(clickup doc create --name "Sprint Notes" --parent-id <space-id> --parent-type 4 --format id)
+clickup doc page-create --doc-id "$DOC_ID" --name "2026-07-04" --content "# Notes\n- item one"
+
+# Append meeting notes as a new page under an existing parent page
+clickup doc page-create --doc-id <doc-id> --name "Standup 2026-07-04" \
+    --parent-page-id <page-id> --content "$(cat notes.md)"
+```
+
+## Notes
+
+- `page-update --content` replaces the page content entirely; read the page first and merge if you need to append.
+- `doc delete` is destructive: it prompts in a terminal and requires `--confirm` in non-interactive mode.
+- Multi-line markdown works best passed via command substitution (`--content "$(cat file.md)"`) to avoid shell quoting issues.
+- Field discovery: `clickup schema doc` lists actions, `clickup schema doc.page-create` shows fields.

package/skills/clickup-fields/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: clickup-fields
 description: Manages ClickUp custom fields, tags, and custom task types. Use when the user asks about custom fields, wants to set field values on tasks, manage tags, or work with custom task types.
-allowed-tools: Bash(clickup custom-field *), Bash(clickup tag *), Bash(clickup custom-task-type *), Bash(clickup attachment *), Bash(clickup schema field*), Bash(clickup schema tag*)
+license: MIT
+allowed-tools: Bash(clickup field *), Bash(clickup tag *), Bash(clickup task-type *), Bash(clickup attachment *), Bash(clickup schema field*), Bash(clickup schema tag*)
 ---
 
 # ClickUp Custom Fields, Tags, and Task Types

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

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose
@@ -12,6 +13,8 @@ allowed-tools: Bash(clickup *)
 
 Track OKR/goal completion, update key results, and identify goals that are at risk.
 
+Interpret `$ARGUMENTS` as the scope (workspace, space, list, person, or time period as the sections below expect); when it is empty, ask or fall back to the configured workspace.
+
 ## Prerequisites
 
 - Workspace ID

package/skills/clickup-goals/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 allowed-tools: Bash(clickup goal *), Bash(clickup schema goal*)
 ---
 

package/skills/clickup-meeting-notes-to-tasks/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: clickup-meeting-notes-to-tasks
+description: Converts meeting notes, transcripts, or brain dumps into triaged ClickUp tasks with assignees, due dates, and tags. Use when the user pastes notes or points at a notes file and wants action items extracted and created as tasks.
+license: MIT
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[list name or ID, then paste notes or give a file path]"
+allowed-tools: Bash(clickup *), Read
+---
+
+# Meeting Notes to Tasks
+
+Extract action items from raw notes and create them as properly triaged tasks.
+
+## Understanding the Input
+
+`$ARGUMENTS` should contain a target list (name or ID) and the notes themselves (pasted text or a file path). If either is missing, ask for it before creating anything.
+
+## Workflow
+
+### Step 1: Resolve the target list
+
+```bash
+# If given a name, find the list ID
+clickup list list --folder-id <id> --format json     # or --space-id for folderless lists
+clickup space list --format json                     # to locate the right space first
+```
+
+### Step 2: Resolve people
+
+Build a name-to-ID map so "Sarah will fix the login bug" becomes an assigned task:
+
+```bash
+clickup member list --format json
+```
+
+Match first names case-insensitively. If a name in the notes matches nobody, leave the task unassigned and note it in the summary.
+
+### Step 3: Extract action items
+
+Read the notes and pull out every commitment, decision requiring follow-up, and explicit todo. For each item capture:
+
+- **name**: imperative, under 80 chars ("Fix login redirect on Safari")
+- **assignee**: from the people map, if a person was named
+- **due date**: explicit dates, or relative phrases ("by Friday" = `friday`, "next week" = `+1w`)
+- **priority**: `urgent` only if the notes say so; otherwise `normal`
+- **description**: the sentence(s) from the notes the item came from, for context
+
+Do NOT create tasks for decisions already made, FYIs, or discussion points with no action.
+
+### Step 4: Confirm the plan
+
+Show the extracted items as a table (name, assignee, due, priority) and ask for approval before creating anything. Skip this only if the user already said to create without review.
+
+### Step 5: Create the tasks
+
+```bash
+clickup task create --list-id <id> --name "<name>" \
+    [--description "<context>"] [--assignee <user-id>] \
+    [--due-date <friday|+3d|2026-07-10>] [--priority <level>] \
+    --format id
+```
+
+Collect the returned IDs. Dates accept ISO 8601, relative forms (`tomorrow`, `3d`, `friday`), or Unix timestamps.
+
+### Step 6: Report
+
+```
+Created N tasks in <list name>:
+- <task name> -> <assignee or unassigned>, due <date> (<task-id>)
+...
+Skipped: <items that were FYI/decisions, one line on why>
+Unmatched people: <names that could not be resolved>
+```
+
+## Tips
+
+- Tag every created task for traceability: `clickup tag add --task-id <id> --name "meeting-2026-07-04"`
+- For a recurring meeting, offer to also create a summary page in a Doc: see the clickup-docs skill.
+- If the notes mention blocking relationships ("can't start X until Y"), add them: `clickup dependency add --task-id <x> --depends-on <y>`

package/skills/clickup-my-day/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: clickup-my-day
+description: Builds a personal daily agenda from ClickUp showing what is due, overdue, in progress, and blocked, ordered by what to tackle first. Use when the user asks what they should work on, wants their day planned, or asks what is on their plate today.
+license: MIT
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[optional: a different person, or 'this week' for a wider window]"
+allowed-tools: Bash(clickup *)
+---
+
+# My Day
+
+Answer one question well: what should I work on right now?
+
+## Understanding the Scope
+
+Default subject is the authenticated user; `$ARGUMENTS` can name someone else or widen the window ("this week"). Resolve the current user by matching the email from `clickup auth status` against `clickup member list --format json`.
+
+## Workflow
+
+### Step 1: Pull my open tasks
+
+```bash
+clickup task search --workspace-id <id> --assignee <user-id> --format json
+```
+
+### Step 2: Check the running timer
+
+```bash
+clickup time running --workspace-id <id> --format json
+```
+
+If a timer is running, its task leads the agenda ("you're mid-flight on this").
+
+### Step 3: Bucket and order
+
+1. **Overdue** - `due_date` in the past (oldest first)
+2. **Due today**
+3. **In progress** - started but not due yet; flag anything untouched for 7+ days
+4. **Blocked/waiting** - list what each is waiting on if dependencies exist
+5. **Up next** - highest priority undated tasks, max 3
+
+Priority (urgent=1 to low=4) breaks ties inside each bucket.
+
+### Step 4: Present the agenda
+
+```
+## Your day - <date>
+
+Now: <running timer task, if any>
+
+1. [OVERDUE] <task> - was due <date> (<list>)
+2. [TODAY] <task> - <priority>
+3. ...
+
+Blocked (not actionable): <task> - waiting on <dependency>
+
+Suggestion: <one sentence - e.g. "Clear the two overdue items before starting new work.">
+```
+
+Keep it under ~10 items; summarize the rest as "and N more in the backlog".
+
+### Step 5: Offer actions
+
+If the user reacts ("push the report to Friday", "start the timer on #2"):
+
+```bash
+clickup task update <id> --due-date friday
+clickup time start --workspace-id <id> --task-id <id>
+```
+
+## Tips
+
+- Dates accept relative forms (`friday`, `+2d`) so rescheduling reads naturally.
+- "This week" widens step 3's due window to the next 7 days but keeps the same buckets.
+- For someone else's day, skip step 5's timer actions - never start timers for other people.

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

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose
@@ -12,6 +13,8 @@ allowed-tools: Bash(clickup *)
 
 Create a complete project structure in ClickUp from scratch.
 
+Interpret `$ARGUMENTS` as the scope (workspace, space, list, person, or time period as the sections below expect); when it is empty, ask or fall back to the configured workspace.
+
 ## Prerequisites
 
 - Workspace ID

package/skills/clickup-release-notes/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: clickup-release-notes
+description: Generates release notes or a changelog from ClickUp tasks completed in a period, grouped by type and written for the chosen audience. Use when the user asks for release notes, a changelog, a "what shipped" summary, or wants completed work written up for customers or stakeholders.
+license: MIT
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[period and scope - e.g. 'last sprint for the mobile space', 'June, customer-facing']"
+allowed-tools: Bash(clickup *), Write
+---
+
+# Release Notes
+
+Turn completed tasks into a changelog worth reading.
+
+## Understanding the Scope
+
+From `$ARGUMENTS` determine: the period (default: since the last tag/release the user mentions, else last 14 days), the scope (workspace, space, or list), and the audience. Audience changes the writing: customer-facing notes describe benefits; internal notes can name tasks and people.
+
+## Workflow
+
+### Step 1: Pull completed tasks
+
+```bash
+clickup task search --workspace-id <id> \
+    --include-closed \
+    --status "complete" --status "closed" --status "done" \
+    --date-updated-gt <period-start-ms> --date-updated-lt <period-end-ms> \
+    [--space-id <id>] --format json
+```
+
+`--date-updated-*` filters take Unix ms; compute them from the period.
+
+### Step 2: Classify
+
+Group by tags and task names into: **Features**, **Improvements**, **Fixes**, and **Internal** (refactors, chores - omit for customer-facing notes). Tags like `bug`, `feature`, `enhancement` decide the bucket; otherwise judge from the task name and description.
+
+### Step 3: Write the notes
+
+Rewrite task names for the audience - "Fix login redirect on Safari" becomes "Fixed an issue where Safari users could be redirected to the wrong page after logging in." Never paste raw task IDs into customer-facing notes.
+
+```markdown
+# Release Notes - <period>
+
+## New
+- ...
+
+## Improved
+- ...
+
+## Fixed
+- ...
+```
+
+For internal notes append task IDs and assignees for traceability.
+
+### Step 4: Deliver
+
+Present the notes in chat. Offer to also:
+
+```bash
+# Publish into a ClickUp Doc
+clickup doc page-create --workspace-id <id> --doc-id <id> \
+    --name "Release Notes <date>" --content "$(cat notes.md)"
+
+# Or save locally
+```
+
+## Tips
+
+- If several statuses mean "done" in this workspace, check `clickup list statuses` conventions first rather than guessing.
+- Exclude subtasks whose parent is already listed to avoid duplicate lines.
+- A count line ("12 improvements shipped by 5 people") makes stakeholder notes land better.

package/skills/clickup-rollout/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clickup-rollout
 description: Rolls out a saved process template in ClickUp by applying it to a target location, then configuring assignees, due dates, and custom fields. Use when the user says "start a new [project/process/sprint/onboarding]" or wants to kick off a repeatable workflow from a template.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose
@@ -12,6 +13,8 @@ allowed-tools: Bash(clickup *)
 
 Apply a saved ClickUp template and configure the resulting task, list, or folder for a new instance of the process.
 
+Interpret `$ARGUMENTS` as the scope (workspace, space, list, person, or time period as the sections below expect); when it is empty, ask or fall back to the configured workspace.
+
 ## Workflow
 
 ### Step 1: Find the template

package/skills/clickup-spaces/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 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*)
 ---
 

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

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose
@@ -12,6 +13,8 @@ allowed-tools: Bash(clickup *)
 
 End a sprint cleanly: summarize what was done, carry over incomplete work, and gather data for a retrospective.
 
+Interpret `$ARGUMENTS` as the scope (workspace, space, list, person, or time period as the sections below expect); when it is empty, ask or fall back to the configured workspace.
+
 ## Prerequisites
 
 - Sprint list ID

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

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose
@@ -12,6 +13,8 @@ allowed-tools: Bash(clickup *)
 
 Set up a new sprint by pulling tasks from the backlog, estimating, assigning, and organizing.
 
+Interpret `$ARGUMENTS` as the scope (workspace, space, list, person, or time period as the sections below expect); when it is empty, ask or fall back to the configured workspace.
+
 ## Prerequisites
 
 - Workspace and space IDs known

package/skills/clickup-standup/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose

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

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose
@@ -12,6 +13,8 @@ allowed-tools: Bash(clickup *)
 
 Sort through incoming/unprocessed tasks: prioritize, assign, add tags, and move to the right lists.
 
+Interpret `$ARGUMENTS` as the scope (workspace, space, list, person, or time period as the sections below expect); when it is empty, ask or fall back to the configured workspace.
+
 ## Prerequisites
 
 - Know the inbox/backlog list ID where new tasks land

package/skills/clickup-tasks/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 allowed-tools: Bash(clickup task *), Bash(clickup checklist *), Bash(clickup dependency *), Bash(clickup relation *), Bash(clickup attachment *), Bash(clickup schema task*), Bash(clickup schema checklist*)
 ---
 

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

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose

package/skills/clickup-templates/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clickup-templates
 description: Lists and applies ClickUp templates to create tasks, lists, and folders from saved process templates. Use when the user wants to roll out a repeatable process, create items from a template, or find what templates are available in the workspace.
+license: MIT
 allowed-tools: Bash(clickup template *), Bash(clickup schema template*)
 ---
 

package/skills/clickup-time/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 allowed-tools: Bash(clickup time *), Bash(clickup schema time*)
 ---
 

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

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose
@@ -12,6 +13,8 @@ allowed-tools: Bash(clickup *)
 
 Audit time tracking data for accuracy, utilization, and completeness.
 
+Interpret `$ARGUMENTS` as the scope (workspace, space, list, person, or time period as the sections below expect); when it is empty, ask or fall back to the configured workspace.
+
 ## Prerequisites
 
 - Workspace ID

package/skills/clickup-timesheet-export/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: clickup-timesheet-export
+description: Exports ClickUp time entries for a period into a timesheet - CSV or markdown - with per-person and per-task totals and billable breakdowns. Use when the user asks for a timesheet, billable hours export, invoice backup, or wants hours summed for payroll or a client.
+license: MIT
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[period and scope - e.g. 'last week', 'June for Sarah', 'this month billable only']"
+allowed-tools: Bash(clickup *), Write
+---
+
+# Timesheet Export
+
+Turn raw time entries into a clean timesheet with totals.
+
+## Understanding the Scope
+
+From `$ARGUMENTS` determine: the period (default: last 7 days), who (default: everyone), and whether to include only billable time. Resolve people via `clickup member list --format json`.
+
+## Workflow
+
+### Step 1: Pull time entries
+
+```bash
+clickup time list --workspace-id <id> \
+    --start <period-start> --end <period-end> \
+    [--assignee <user-id>] --format json
+```
+
+`--start`/`--end` accept ISO dates (`2026-06-01`), relative forms (`-30d`), or Unix timestamps. Entry durations are milliseconds.
+
+### Step 2: Aggregate
+
+Compute from the JSON:
+
+- Hours per person per day (duration ms / 3,600,000, round to 2 decimals)
+- Hours per task (join `task.id` to task names from the entries)
+- Billable vs non-billable split (the `billable` field)
+- Grand totals
+
+### Step 3: Write the export
+
+CSV for spreadsheets (default when the user says export/invoice):
+
+```csv
+date,person,task,description,hours,billable
+2026-06-30,Sarah,Login bug fix,Safari redirect,2.50,true
+```
+
+Save with the Write tool as `timesheet-<start>-<end>.csv` and tell the user the path. For a chat answer, use a markdown table plus totals instead.
+
+### Step 4: Summarize
+
+```
+Timesheet <start> to <end>
+- Total: N hours (M billable / K non-billable)
+- By person: Sarah 32.5h, Tom 28.0h, ...
+- Top tasks: <task> 12.5h, ...
+Flagged: entries with no task attached, running timers still open
+```
+
+## Tips
+
+- Entries with a null `end` are running timers; exclude them from totals and flag them.
+- Cross-check suspicious days (over 12h per person) rather than silently exporting them.
+- For a recurring client invoice, filter to the client's space via the task IDs' locations.

package/skills/clickup-users/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 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*)
 ---
 

package/skills/clickup-views/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 allowed-tools: Bash(clickup view *), Bash(clickup schema view*)
 ---
 

package/skills/clickup-webhooks/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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.
+license: MIT
 allowed-tools: Bash(clickup webhook *), Bash(clickup schema webhook*)
 ---
 

package/skills/clickup-weekly-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clickup-weekly-review
 description: Generates a weekly progress report from ClickUp, scoped to any team, department, space, or workspace. Summarizes completed tasks, in-progress work, blockers, and time logged. Use when the user asks for a weekly update, progress report, team summary, department rundown, or wants to know what happened this week.
+license: MIT
 disable-model-invocation: true
 context: fork
 agent: general-purpose

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

@@ -0,0 +1,80 @@
+---
+name: clickup-workspace-audit
+description: Runs a hygiene audit over a ClickUp workspace or space finding unassigned tasks, missing due dates, stale in-progress work, overdue items, and overloaded assignees. Use when the user asks to audit, clean up, or health-check their workspace, or asks what is falling through the cracks.
+license: MIT
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[scope - workspace, space name, or list name; optionally 'and fix']"
+allowed-tools: Bash(clickup *)
+---
+
+# Workspace Audit
+
+Find hygiene problems across active tasks and report them with recommended fixes.
+
+## Understanding the Scope
+
+Interpret `$ARGUMENTS`: no scope means the whole workspace; a space or list name narrows the sweep (`--space-id` / `--list-id` filters on `task search`). If the user said "and fix" (or similar), offer to apply the recommended fixes after the report; never modify tasks without that instruction.
+
+## Workflow
+
+### Step 1: Pull the active task set
+
+```bash
+clickup task search --workspace-id <id> --format json
+```
+
+Server-side filters cannot express "no assignee" or "no due date", so fetch active tasks and inspect the JSON client-side. For large workspaces sweep one space at a time (`--space-id`).
+
+### Step 2: Detect problems
+
+Classify each task into any of:
+
+| Check | Condition |
+|-------|-----------|
+| Unassigned | `assignees` is empty |
+| No due date | `due_date` is null |
+| Overdue | `due_date` in the past, status not closed |
+| Stale | status is in progress but `date_updated` older than 14 days |
+| Overloaded assignee | one person holds a disproportionate share of open tasks (flag the top offenders) |
+
+### Step 3: Check for blocked chains (optional, if dependencies are used)
+
+Tasks with `blocked` or `waiting` status whose blockers are themselves overdue deserve a callout.
+
+### Step 4: Report
+
+```
+## Workspace Audit: <scope> (<date>)
+
+Overall: N active tasks, M flagged (X%)
+
+### Overdue (worst first)
+- <task> - due <date>, assignee <name> (<id>)
+
+### Unassigned / No due date / Stale
+- ...
+
+### Load
+- <name>: N open tasks (team median: M)
+
+### Recommended fixes
+1. ...
+```
+
+### Step 5: Apply fixes (only when asked)
+
+```bash
+clickup task update <id> --assignee-add <user-id>      # assign
+clickup task update <id> --due-date friday             # set due date
+clickup task update <id> --status "backlog"            # demote stale work honestly
+```
+
+Confirm the fix list with the user before running it; report each change as it lands.
+
+## Tips
+
+- `--include-closed` stays off: the audit is about active work.
+- Dates accept relative forms (`friday`, `+1w`) so fixes read naturally.
+- Re-run after fixes and show the before/after flagged counts.