clickup

clickup

目的

このスキルを使うと、AI が ClickUp の API を操作し、プロジェクトのタスク、スペース、リスト、ドキュメント、目標、ダッシュボード、自動化、時間追跡、インテグレーションを管理できます。ClickUp のデータをプログラムから取得または更新し、ワークフローを自動化するために使用します。

使用するタイミング

アプリ間でタスクを同期する、ClickUp のデータからレポートを生成する、イベントに応じてタスクの作成を自動化する、CI/CD パイプラインと連携するなど、コードを使った生産性向上タスクを行うときに、このスキルを使用します。プロジェクト管理の自動化スクリプトや、チャットボットや監視ツールのようにリアルタイムの更新が必要な場合に適用します。

主な機能

• タスクを管理します。タスクの作成には、POST /api/v2/list/{list_id}/task などの API エンドポイントを使用します。
• スペースとリストを扱います。スペースの取得には、GET /api/v2/team/{team_id}/space を使用します。
• ドキュメントと目標にアクセスします。ドキュメントの取得には、GET /api/v2/folder/{folder_id}/doc を使用します。
• POST /api/v2/task/{task_id}/time_entry などのエンドポイントで時間を追跡します。
• GET /api/v2/space/{space_id}/automation で取得する ClickUp の自動化ルールを使って、ワークフローを自動化します。
• GET /api/v2/team/{team_id}/dashboard でダッシュボードを使用します。
• すべての操作で、Authorization ヘッダーの Bearer トークンによる認証が必要です。
• 大規模なデータセットでは、?page=1&limit=50 のようなクエリパラメーターを使ったページネーションに対応しています。

使用パターン

環境変数（例：$CLICKUP_API_TOKEN）に保存した API トークンで、必ずリクエストを認証してください。Python の requests などの HTTP ライブラリを使って API を呼び出します。たとえば、ベース URL https://api.clickup.com/api/v2 を指定してリクエストを作成し、JSON ペイロードを処理します。基本的な流れとして、まず GET /api/v2/team でチーム ID を取得し、それを使ってネストされたリソースにアクセスします。レート制限が発生した場合は、指数バックオフを実装してください。CLI と連携する場合は、出力を jq などのツールにパイプして JSON レスポンスを解析します。

一般的なコマンド／API

• タスクを作成する：JSON 本文 {"name": "New Task", "description": "Details"} を付けて POST /api/v2/list/{list_id}/task を使用します。Python の例：

  import requests; token = os.environ['CLICKUP_API_TOKEN']
  response = requests.post('https://api.clickup.com/api/v2/list/123/task', headers={'Authorization': token}, json={'name': 'Task'})
  

• リスト内のタスクを取得する：GET /api/v2/list/{list_id}/task?subtasks=true。CLI の例：curl -H "Authorization: $CLICKUP_API_TOKEN" https://api.clickup.com/api/v2/list/456/task
• タスクを更新する：本文 {"status": "in progress"} を付けて PUT /api/v2/task/{task_id} を使用します。コード例：

  requests.put('https://api.clickup.com/api/v2/task/789', headers={'Authorization': token}, json={'status': 'complete'})
  

• スペースを取得する：GET /api/v2/team/{team_id}/space。設定形式：チーム ID を .env ファイルに CLICKUP_TEAM_ID=123 として保存します。
• 時間追跡：{"start": "2023-01-01T00:00:00Z"} を付けて POST /api/v2/task/{task_id}/time_entry を使用します。

インテグレーションに関する注意

ClickUp アカウントの設定から $CLICKUP_API_TOKEN をエクスポートして認証を設定します。インテグレーションでは、ClickUp の Webhook（例：POST /api/v2/webhook で登録）を使用し、アプリで受信ペイロードを処理します。他のサービスと連携する際は、ClickUp の ID（例：タスク ID）を外部キーに対応付けます。設定形式：{"api_base": "https://api.clickup.com/api/v2", "team_id": "123"} のような JSON 設定ファイルを使用します。トークンをハードコードせず、必ず環境変数を使用してください。OAuth が必要な場合は、ユーザーを ClickUp の認証フローにリダイレクトします。ただし、API へのアクセスにはトークンベースの認証を使用してください。

エラー処理

HTTP ステータスコードを確認します。401 は未認証（新しいトークンで再試行）、429 はレート制限（待機してバックオフ後に再試行）、404 は見つからない（ログに記録してスキップ）を示します。JSON エラーを解析します。たとえば、response.json()['err'] == 'Access denied' の場合は、カスタム例外を発生させます。コードでは、リクエストを try-except ブロックで囲みます。

try: response = requests.get(url, headers={'Authorization': token})
except requests.exceptions.RequestException as e: print(f"Error: {e}, Status: {response.status_code}")

レスポンスに 'next_page' があるか確認して、ページネーションのエラーを処理します。API 呼び出し前に list_id が整数であることを確認するなど、入力を検証してください。

具体的な使用例

1. タスク作成を自動化する：ユーザーがチャットで新しいタスクを依頼したら、このスキルを使って ClickUp に作成します。例：スクリプトでユーザーの入力を解析し、タスクの詳細を指定して POST /api/v2/list/123/task を呼び出します。コード：

   task_data = {'name': 'User-reported issue', 'description': user_input}
   requests.post('https://api.clickup.com/api/v2/list/123/task', headers={'Authorization': $CLICKUP_API_TOKEN}, json=task_data)
   

   これにより、メッセージングアプリと連携してリアルタイムでタスクを管理できます。

2. タスクを取得して報告する：日次サマリーを作成するには、スペース内のタスクを照会し、ステータスで絞り込みます。例：GET /api/v2/space/456/task?status=active を使用し、レスポンスを処理して未完了のタスク数を集計します。コード：

   response = requests.get('https://api.clickup.com/api/v2/space/456/task', headers={'Authorization': $CLICKUP_API_TOKEN})
   tasks = response.json()['tasks']; open_tasks = [t for t in tasks if t['status']['status'] == 'active']
   print(f"Open tasks: {len(open_tasks)}")
   

   これは、生産性向上ツールのダッシュボード更新やアラートに役立ちます。

グラフの関係

• 関連クラスター：コミュニティ（例：GitHub や Trello のスキルなど、他のコミュニティツールへのリンク）。
• タグ：clickup（直接一致）、tasks（プロジェクト管理スキルに関連）、project（Jira や Asana に相当するツールへのリンク）、productivity（時間追跡や自動化スキルに関連）。