Calcom Access

Cal.com Access

Manage Cal.com bookings and event types programmatically via Claude Code.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

MANDATORY PREFLIGHT (Execute Before Any Cal.com Operation)

CRITICAL: You MUST complete this preflight checklist before running any Cal.com commands. Do NOT skip steps.

Step 1: Check CLI Binary Exists

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

If BINARY_NOT_FOUND: Build it first:

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

Step 2: Check CALCOM_OP_UUID Environment Variable

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

If NOT_SET: You MUST run the Setup Flow below. Do NOT proceed to Cal.com commands.

Step 3: Verify 1Password Authentication

op account list 2>&1 | head -3

If error or not signed in: Inform user to run op signin first.

Step 4: Test API Connectivity

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

---

Setup Flow (When CALCOM_OP_UUID is NOT_SET)

Follow these steps IN ORDER. Use AskUserQuestion at decision points.

Setup Step 1: Check 1Password CLI

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

If OP_CLI_MISSING: Stop and inform user:

1Password CLI is required. Install with: brew install 1password-cli

Setup Step 2: Discover Cal.com API Keys in 1Password

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

Parse the output and proceed based on results.

Setup Step 3: User Selects API Credentials

If items found, use AskUserQuestion with discovered items.

If NO items found, guide the user:

1. Log into the Cal.com instance (self-hosted or cal.com) 2. Go to Settings > Developer > API Keys 3. Generate a new API key with appropriate scopes 4. Store in 1Password Claude Automation vault:

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

Setup Step 4: Configure mise

After user selects an item (with UUID), use AskUserQuestion to confirm adding to .mise.local.toml:

[env]
CALCOM_OP_UUID = "<selected-uuid>"

Setup Step 5: Reload and Verify

mise trust 2>/dev/null || true
cd . && echo "CALCOM_OP_UUID after reload: ${CALCOM_OP_UUID:-NOT_SET}"

Setup Step 6: Test Connection

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

---

Cal.com Commands (Only After Preflight Passes)

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 Reference

Environment Variables

References

• calcom-api-setup.md - Cal.com API key setup guide
• mise-setup.md - Step-by-step mise configuration

Post-Change Checklist

• [ ] YAML frontmatter valid (no colons in description)
• [ ] Trigger keywords current
• [ ] Path patterns use $HOME not hardcoded paths
• [ ] References exist and are linked

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path before editing. 1. What failed? — Fix the instruction that caused it. 2. What worked better than expected? — Promote to recommended practice. 3. What drifted? — Fix any script, reference, or dependency that no longer matches reality. 4. Log it. — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

Cal.com API Setup Guide

How to obtain and configure Cal.com API credentials for autonomous CLI access.

Option A: Self-Hosted Instance (Recommended)

If you've deployed Cal.com via Cloud Run or Docker Compose:

1. Log into your Cal.com instance (e.g., https://calcom-your-project.run.app) 2. Go to Settings > Developer > API Keys 3. Click Create new API key 4. Set expiration (or "Never" for automation) 5. Copy the generated key

Option B: Cal.com Cloud (cal.com)

1. Log into cal.com 2. Go to Settings > Developer > API Keys 3. Create a new key with appropriate permissions 4. Copy the generated key

Store in 1Password

op item create --category "API Credential" \
  --title "Cal.com API Key" \
  --vault "Claude Automation" \
  "credential=cal_live_xxxxxxxxxxxx" \
  "api_url=https://your-calcom-instance.run.app"

Note the UUID from the output — this becomes your CALCOM_OP_UUID.

Configure mise

Add to your project's .mise.local.toml (gitignored):

[env]
CALCOM_OP_UUID = "<uuid-from-1password>"
CALCOM_API_URL = "https://your-calcom-instance.run.app"

Verify

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

API v2 Documentation

• Cal.com API v2 Docs
• Base URL: https://api.cal.com/v2 (cloud) or https://your-instance/api/v2 (self-hosted)
• Authentication: Bearer token in Authorization header

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

mise Configuration for Cal.com Commander

Step-by-step guide for configuring mise environment variables.

Two-Layer Pattern

Cal.com Commander uses the standard two-layer mise pattern:

Required Variables

Add these to .mise.local.toml in your project directory:

[env]
# Cal.com API
CALCOM_OP_UUID = "<1password-item-uuid>"
CALCOM_API_URL = "https://your-instance.run.app"

# Telegram Bot
TELEGRAM_BOT_TOKEN = "<bot-token>"
TELEGRAM_CHAT_ID = "<chat-id>"

# AI Model
HAIKU_MODEL = "claude-haiku-4-5-20251001"

# GCP (for deployment)
CALCOM_GCP_PROJECT = "<gcp-project-id>"
CALCOM_GCP_ACCOUNT = "<gcp-account-email>"
CALCOM_GCP_BILLING = "<billing-account-id>"
CALCOM_GCP_REGION = "us-central1"

# Supabase
SUPABASE_PROJECT_REF = "<supabase-project-ref>"
SUPABASE_DB_URL_REF = "op://Claude Automation/<item-id>/DATABASE_URL"
SUPABASE_DB_DIRECT_URL_REF = "op://Claude Automation/<item-id>/DATABASE_DIRECT_URL"
SUPABASE_ACCESS_TOKEN_REF = "op://Claude Automation/<item-id>/credential"

# Cal.com Secrets (1Password)
CALCOM_NEXTAUTH_SECRET_REF = "op://Claude Automation/<item-id>/NEXTAUTH_SECRET"
CALCOM_ENCRYPTION_KEY_REF = "op://Claude Automation/<item-id>/CALENDSO_ENCRYPTION_KEY"
CALCOM_CRON_API_KEY_REF = "op://Claude Automation/<item-id>/CRON_API_KEY"

Verify

# Trust the config
mise trust

# Check all variables are loaded
mise env | grep -E "CALCOM|TELEGRAM|SUPABASE"

Gitignore

Ensure .mise.local.toml is in your .gitignore:

grep -q '.mise.local.toml' .gitignore || echo '.mise.local.toml' >> .gitignore