calcom-access

Cal.com 访问

通过 Claude Code 以编程方式管理 Cal.com 预约和事件类型。

自我演进的技能：此技能会随着使用不断改进。如果指令有误、参数发生偏移，或需要采用变通方法，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

强制预检（执行任何 Cal.com 操作前）

重要：运行任何 Cal.com 命令前，必须完成此预检清单。切勿跳过任何步骤。

步骤 1：检查 CLI 二进制文件是否存在

ls -la "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom" 2>/dev/null || echo "BINARY_NOT_FOUND"

如果为 BINARY_NOT_FOUND：先构建：

cd ~/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli && bun install && bun run build

步骤 2：检查 CALCOM_OP_UUID 环境变量

echo "CALCOM_OP_UUID: ${CALCOM_OP_UUID:-NOT_SET}"

如果为 NOT_SET：必须运行下方的设置流程。不要继续执行 Cal.com 命令。

步骤 3：验证 1Password 身份验证

op account list 2>&1 | head -3

如果出错或尚未登录：告知用户先运行 op signin。

步骤 4：测试 API 连通性

CALCOM_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom"
$CALCOM_CLI event-types list 2>&1 | head -5

---

设置流程（当 CALCOM_OP_UUID 为 NOT_SET 时）

按顺序执行以下步骤。在需要做决定时使用 AskUserQuestion。

设置步骤 1：检查 1Password CLI

command -v op && echo "OP_CLI_INSTALLED" || echo "OP_CLI_MISSING"

如果为 OP_CLI_MISSING：停止并告知用户：

需要 1Password CLI。使用以下命令安装：brew install 1password-cli

设置步骤 2：在 1Password 中查找 Cal.com API 密钥

op item list --vault "Claude Automation" --format json 2>/dev/null | jq -r '.[] | select(.title | test("calcom|cal.com|calendar"; "i")) | "\(.id)\t\(.title)"'

解析输出，并根据结果继续操作。

设置步骤 3：用户选择 API 凭据

如果找到条目，使用 AskUserQuestion 并提供找到的条目供用户选择。

如果未找到条目，引导用户：

1. 登录 Cal.com 实例（自托管或 cal.com）
2. 前往 Settings > Developer > API Keys
3. 生成具有相应权限范围的新 API 密钥
4. 将其存储到 1Password Claude Automation 保管库：

op item create --category "API Credential" --title "Cal.com API Key" \
  --vault "Claude Automation" \
  "credential=<api-key>" \
  "api_url=<cal.com-instance-url>"

设置步骤 4：提供 UUID

用户选择条目（含 UUID）后，使用 AskUserQuestion 确认该值的保存位置：仅用于当前 Shell（export CALCOM_OP_UUID=<selected-uuid>），还是用于 launchd 守护进程（将 export CALCOM_OP_UUID='<selected-uuid>' 添加到 ~/gh/<org>/<automation-repo>/.env.launchd，启动器脚本会加载该文件）。

设置步骤 5：验证

echo "CALCOM_OP_UUID: ${CALCOM_OP_UUID:-NOT_SET}"

设置步骤 6：测试连接

CALCOM_OP_UUID="${CALCOM_OP_UUID}" $HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom event-types list

---

Cal.com 命令（仅在预检通过后）

CALCOM_CLI="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/calcom-commander/scripts/calcom-cli/calcom"

# List event types
$CALCOM_CLI event-types list

# List bookings
$CALCOM_CLI bookings list -n 10

# List bookings by status
$CALCOM_CLI bookings list --status upcoming -n 20

# Get booking details
$CALCOM_CLI bookings get <booking_id>

# Create event type
$CALCOM_CLI event-types create --title "30min Interview" --slug "interview-30" --length 30

# Update event type
$CALCOM_CLI event-types update <event_type_id> --title "Updated Title"

# List schedules (availability)
$CALCOM_CLI schedules list

# JSON output (for parsing)
$CALCOM_CLI bookings list -n 10 --json

Cal.com API v2 参考

端点	CLI 命令	说明
事件类型	event-types list	列出所有事件类型
事件类型	event-types create	创建新的事件类型
预约	bookings list	列出预约
预约	bookings get	获取预约详情
预约	bookings cancel	取消预约
日程	schedules list	列出可用时间段
日程	schedules create	创建可用时间
可用性	availability check	检查时段可用性

环境变量

变量	必需	说明
CALCOM_OP_UUID	是	API 密钥对应的 1Password 条目 UUID
CALCOM_API_URL	否	API 基础 URL（默认：自托管）

参考资料

• calcom-api-setup.md - Cal.com API 密钥设置指南
• env-setup.md - 各变量的来源及其使用者

变更后检查清单

• YAML frontmatter 有效（description 中不含冒号）
• 触发关键词为最新
• 路径模式使用 $HOME，而非硬编码路径
• 参考文件存在且已链接

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确认位置。——编辑前，找到此 SKILL.md 的规范路径。
1. 哪里失败了？——修复导致问题的指令。
2. 哪些做得比预期更好？——将其列为推荐做法。
3. 哪里偏离了？——修复任何与实际情况不符的脚本、参考资料或依赖项。
4. 记录下来。——在演进日志中记录触发原因、修复内容和证据。

不要推迟。下一次调用会继承你留下的一切。