---

name: clickup-push-tasks description: Push a local task file to ClickUp as a new task with subtasks. Use when you have a structured task file (docs/tasks/*.md) and want to create visibility in ClickUp for clients or team members. Creates parent task + phases as subtasks + items as sub-subtasks.

ClickUp Push Tasks

Create a ClickUp task hierarchy from a local task markdown file.

Invocation

Copy/clickup-push-tasks <path-to-task-file>
/clickup-push-tasks docs/tasks/my-feature.md
/clickup-push-tasks ./outputs/project/tasks.md

Arguments:

• Required: Path to a task file in the standard format (see Task File Format below)

Prerequisites

• ClickUp Access Token - Set in ~/.claude/skills/clickup-push-tasks/.env (see .env.example for setup)

Task File Format

The task file must follow the standard format:

Copy# Task: <Title>

> Optional summary description

**Type:** development | research | documentation
**Branch:** feat/<id>  (optional)

---

## Context

Description of the task for business users.

---

## Tasks

### Phase 1: <Phase Name>

- [ ] Task item one
  - File: `path/to/file.ts`
- [ ] Task item two
- [x] Completed item

### Phase 2: <Another Phase>

- [ ] More tasks here

Workflow

Step 1: Validate Environment

Copynpx tsx ~/.claude/skills/clickup-push-tasks/scripts/clickup-api.ts validate

If token is missing, instruct user to set CLICKUP_ACCESS_TOKEN in ~/.claude/skills/clickup-push-tasks/.env.

Step 2: Parse Task File

Copynpx tsx ~/.claude/skills/clickup-push-tasks/scripts/task-parser.ts <taskFilePath>

Validate the output has:

• title - Required for parent task name
• phases - At least one phase with items

If missing, report error and exit.

Step 3: Ask User for Destination and Status

Fetch workspace and space hierarchy:

Copynpx tsx ~/.claude/skills/clickup-push-tasks/scripts/clickup-api.ts workspaces
npx tsx ~/.claude/skills/clickup-push-tasks/scripts/clickup-api.ts spaces <workspaceId>
npx tsx ~/.claude/skills/clickup-push-tasks/scripts/clickup-api.ts lists <spaceId>

The spaces command returns available statuses for each space.

IMPORTANT: Status names are case-sensitive. Use the EXACT status values returned by the API (e.g., "Open", "backlog", "Closed" - not normalized to lowercase).

Use AskUserQuestion to prompt user:

1. Which Space? (Engineering, Marketing, etc.)
2. Which List? (Backlog, Sprint, etc.)
3. Initial Status? (Use EXACT status values from the selected space's statuses array)

Store the selected status (with exact casing) for use when creating tasks.

Step 4: Create Parent Task

Create the main task in the selected list with the selected status:

Copynpx tsx ~/.claude/skills/clickup-push-tasks/scripts/clickup-api.ts create-task <listId> "<title>" "<description>" --status=<selectedStatus>

• Name: From task file # Task: <title> (or main heading if no Task: prefix)
• Description: From the Context section of the task file
• Status: The status selected in Step 3

Note the created task ID from the response.

Step 4.5: Generate Business Descriptions

Before creating subtasks, generate a business-friendly description for each task item. This is the key step that makes tasks understandable to business users.

For each phase and task item, create a description following this framework:

Phase Description Template:

CopyThis phase focuses on [high-level goal]. Completing these tasks will [business outcome].

Tasks: X items | Status: Y completed

Task Item Description Template:

Copy**What:** [Plain English explanation of what will be done]

**Why:** [Business reason - why this matters to the project/users]

**Outcome:** [What success looks like - measurable if possible]

---
Phase: {phase name}
File: {file path} (if applicable)

Example Transformation:

Input task item:

Copy- [ ] **Task 2.1: Implement core logic**
  - File: `src/core/processor.ts`

Generated description:

Copy**What:** Build the main processing engine that validates and transforms user input into the required output format.

**Why:** This is the core functionality that enables the entire feature. Without it, no user requests can be processed.

**Outcome:** Processing function accepts input, validates against schema, transforms data, and returns structured response. Unit tests pass with >80% coverage.

---
Phase: Core Implementation
File: src/core/processor.ts

Guidelines for generating descriptions:

• Use plain English, avoid jargon
• Focus on business value, not technical implementation details
• Make outcomes specific and measurable when possible
• Keep descriptions concise but informative (3-5 sentences total)

Step 5: Create Subtask Hierarchy

Create tasks manually with the generated descriptions (do NOT use sync-from-file).

Use the --status flag to set the initial status selected in Step 3.

5a. Create Phase Subtasks

For each phase, create a phase subtask with its generated description:

Copynpx tsx ~/.claude/skills/clickup-push-tasks/scripts/clickup-api.ts create-subtask <parentTaskId> "<phase name>" "<phase description>" --status=<selectedStatus>

Note the phase task ID from the response.

5b. Create Item Subtasks

For each task item in the phase, create an item subtask under the phase task:

Copynpx tsx ~/.claude/skills/clickup-push-tasks/scripts/clickup-api.ts create-subtask <phaseTaskId> "<item name>" "<generated description>" --status=<selectedStatus>

5c. Mark Completed Items

If the item is already completed ([x] in the task file), update its status to CLOSED (overrides the initial status):

Copynpx tsx ~/.claude/skills/clickup-push-tasks/scripts/clickup-api.ts update-status <itemTaskId> "CLOSED"

Rate Limiting: Add ~100ms delay between API calls to avoid hitting the 100 req/min limit.

Step 5.5: Save Mapping File

Create a mapping file at .clickup-sync/<parentTaskId>.json to enable future sync-completion:

Copy{
  "parentTaskId": "<id>",
  "taskFile": "<path to task file>",
  "syncedAt": "<ISO timestamp>",
  "phases": {
    "<phase name>": {
      "clickupId": "<phase task id>",
      "items": {
        "<item text>": "<item task id>"
      }
    }
  }
}

Use the Write tool to create this file. Ensure the .clickup-sync/ directory exists first.

Step 6: Update Task File with ClickUp Link

Add the ClickUp URL to the task file if not present:

If the task file doesn't have a **ClickUp:** line, add it after the title block:

Copy**ClickUp:** https://app.clickup.com/t/<taskId>

Step 7: Report Results

Display to user:

• Created task URL (clickable)
• Number of phases created
• Number of items created
• Path to mapping file (.clickup-sync/<taskId>.json)

Example Output

CopyCreated ClickUp task hierarchy:

Parent Task: https://app.clickup.com/t/868h2xyz

Phase: Database Schema
  Description: This phase focuses on setting up the data foundation. Completing these tasks will enable user data storage and retrieval.
  - Add user table migration
    What: Create database migration to add users table with required columns
    Why: Users need persistent storage for account information
    Outcome: Migration runs successfully, users table exists with correct schema
  - Create indexes
  - Add seed data

Phase: API Endpoints
  Description: This phase focuses on building the REST API layer. Completing these tasks will allow frontend to interact with user data.
  - GET /users endpoint
  - POST /users endpoint
  - PUT /users/:id endpoint
  - DELETE /users/:id endpoint

Total: 2 phases, 7 items
Mapping saved to: .clickup-sync/868h2xyz.json

In ClickUp, each task item will have a rich description like:

Copy**What:** Create database migration to add users table with all required columns (id, email, name, created_at, updated_at).

**Why:** Users need persistent storage for their account information. This is the foundation for all user-related features.

**Outcome:** Migration runs successfully in all environments. Users table exists with correct schema and constraints. Rollback migration also works.

---
Phase: Database Schema
File: src/migrations/001_create_users.ts

Error Handling