核心功能
ClickUp Skill 是一款面向企业级代理机构的项目管理集成工具，深度整合 ClickUp 平台能力，提供从任务创建到高级分析的全链路支持。
核心用法
该 Skill 采用层级化工作空间架构（Team → Spaces → Folders → Lists → Tasks），支持跨多个工作空间的无缝切换。用户通过 get_teams 获取工作空间列表后，可在 Elevated、Atrium、Winch Life 等不同空间间自由操作。所有任务操作默认自动包含子任务（subtasks），避免遗漏 70% 以上的实际工作内容。
主要功能模块包括：
- 完整 CRUD 操作：空间、文件夹、列表、任务、自定义字段的全生命周期管理
- 高级报表与分析：任务数量统计、负责人工作负载分布、状态/优先级 breakdown、每日站会报告，均支持自动分页和子任务聚合
- 时间追踪与计费：内置计时器（start/stop timer）和手动时间条目创建，支持账单生成
- 文档管理（API v3）：创建文档和页面，支持与任务关联
- 任务关系映射：依赖关系（blocking/waiting on）和任意任务链接（linked tasks）
- 销售管道与客户组织：按客户文件夹结构化项目，追踪提案、谈判和项目生命周期状态
- retainer 与周期性计费管理
显著优点
1. 自动子任务处理：区别于基础 API 调用，所有查询方法强制包含 subtasks，确保数据完整性
2. 智能分页：get_all_tasks 自动处理分页直到数据完全获取，开发者无需关心 100 req/min 的速率限制细节
3. 多工作空间原生支持：无需切换 API token，单 token 管理多个 client workspace
4. 代理工作流优化：预置客户文件夹结构（Client Overview / Completed Work）、销售管道状态、计费支持
5. 双向依赖管理：清晰区分 "depends_on"（任务被阻塞）和 "waiting_on"（任务阻塞他人）两种关系
潜在局限
1. 文档页面 API 限制：页面创建仍处于 Beta 阶段，需通过 ClickUp UI 完成
2. 速率限制刚性：100 requests/minute 的限制在批量操作时可能成为瓶颈
3. ID 管理复杂度：跨层级操作需要显式传递 workspace/space/folder/list/task ID，学习曲线陡峭
4. 时间戳精度要求：所有时间相关参数需以毫秒为单位，易因单位错误导致异常
5. 自定义任务 ID 双参数要求：使用 custom_task_ids 时必须同时提供 custom_task_ids=true 和 team_id
适合人群
- 管理多客户的数字营销/创意代理机构
- 需要跨工作空间统一视图的项目经理
- 依赖数据驱动决策的团队（需 workload、velocity 报表）
- 使用 ClickUp 作为单一数据源的企业团队
- 有 Python 自动化需求的技术型项目经理
常规风险
- 权限泄露风险：API token 具有工作空间级权限，泄露后可访问所有授权内容
- 误操作跨工作空间：未验证 team_id 时可能在错误 workspace 创建/修改数据
- 数据完整性风险：批量更新操作无事务回滚机制，失败时可能产生脏数据
- 速率限制导致中断：未处理 429 响应的脚本可能在关键操作时失败
- 时间追踪精度争议：毫秒级存储与人工记录习惯可能存在差异，引发计费纠纷
安全建议
- 将 CLICKUP_API_TOKEN 存储于环境变量或密钥管理服务，避免硬编码
- 生产环境操作前，先用
get_teams确认目标 workspace - 批量操作添加指数退避重试机制
- 关键修改操作前导出备份