terrylica 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:
- Log into the Cal.com instance (self-hosted or cal.com)
- Go to Settings > Developer > API Keys
- Generate a new API key with appropriate scopes
- 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
| Endpoint | CLI Command | Description |
|---|---|---|
| Event Types | event-types list |
List all event types |
| Event Types | event-types create |
Create new event type |
| Bookings | bookings list |
List bookings |
| Bookings | bookings get |
Get booking details |
| Bookings | bookings cancel |
Cancel a booking |
| Schedules | schedules list |
List availability windows |
| Schedules | schedules create |
Create availability |
| Availability | availability check |
Check slot availability |
Environment Variables
| Variable | Required | Description |
|---|---|---|
CALCOM_OP_UUID |
Yes | 1Password item UUID for API key |
CALCOM_API_URL |
No | API base URL (default: self-hosted) |
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:
- Locate yourself. — Find this SKILL.md's canonical path before editing.
- What failed? — Fix the instruction that caused it.
- What worked better than expected? — Promote to recommended practice.
- What drifted? — Fix any script, reference, or dependency that no longer matches reality.
- Log it. — Evolution-log entry with trigger, fix, and evidence.
Do NOT defer. The next invocation inherits whatever you leave behind.