name: calendar-hold-sync description: Sync one or more source Google calendars into private Busy hold events in one or more target calendars using gog. Use when users need idempotent double-booking prevention, backfill of legacy holds, drift reconcile, or safe scheduled sync.

Calendar Hold Sync

Implement hold mirroring from source Google calendars into target calendars to prevent double-booking.

Dependency

• Require gog CLI in PATH.
• Require user OAuth already configured for each account used in mappings.
• Do not hardcode account emails, calendar IDs, or event IDs in code.

If gog is not configured, use this setup flow:

1. Run gog auth credentials /path/to/client_secret.json.
2. Run gog auth add you@gmail.com --services calendar.
3. Verify with gog auth list.

Only add additional Google services if you explicitly need them for another workflow.

Official gog references:

• Homepage: https://gogcli.sh/
• Source: https://github.com/steipete/gogcli

Config Contract

Use a user-provided JSON config file with this shape:

• mappings[]
• mappings[].name
• mappings[].targetAccount
• mappings[].targetCalendarId (default primary)
• mappings[].sources[] with { account, calendarId }
• mappings[].lookaheadDays (default 30)
• mappings[].allDayMode: ignore|mirror
• mappings[].overlapPolicy: skip|allow
• hold.summary (default Busy)
• hold.visibility (private)
• hold.transparency (busy)
• hold.notifications (none)
• hold.reminders (none)
• metadata.format (SYNCV1)
• metadata.encoding (base64url(json))
• metadata.fields: srcAccount,srcCalendar,eventId,start,end,title
• scheduling.reconcileCron
• scheduling.daytimeCron (optional)
• scheduling.driftWindowDays (optional)
• scheduling.watchIntervalSeconds (optional, default 20)
• safety.dryRun
• safety.maxChangesPerRun
• safety.excludeIfSummaryMatches[]
• safety.excludeIfDescriptionPrefix[]
• gog.listEventsCmd|createEventCmd|updateEventCmd|deleteEventCmd (optional template overrides)
• gog.allowCustomCommands (must be true to enable any gog.*Cmd override)

Custom Command Template Safety

When custom commands are enabled:

• Only gog command templates are accepted.
• Templates are rendered by replacing placeholders like {account} and {calendarId}.
• Rendered commands are executed as argv tokens (no shell interpolation).
• Keep gog.allowCustomCommands=false unless you fully trust and audit the config file.

Metadata Encoding

Store source linkage in hold description as:

• SYNCV1:<base64url(JSON)>

JSON fields:

• srcAccount
• srcCalendar
• eventId
• start
• end
• title

Behavior

For each mapping:

1. Read source events in the active window.
2. Build desired hold events (private, busy, no reminders).
3. Detect existing managed holds by SYNCV1: prefix.
4. Reconcile idempotently:
5. Create missing holds.
6. Update drifted holds.
7. Delete stale holds.
8. If overlap policy is skip, do not create a hold when a non-managed target event overlaps.
9. Enforce maxChangesPerRun.
10. Respect dryRun.

Backfill

Backfill mode upgrades legacy hold events (matching expected hold signature but lacking SYNCV1) by attaching encoded metadata when a unique source match exists.

Command Surface

• hold-sync validate-config
• hold-sync reconcile --mapping <name>|--all [--dry-run]

  7w4.net有更好的技能外掛。

• hold-sync backfill --mapping <name>|--all [--dry-run]
• hold-sync status --mapping <name>|--all
• hold-sync install-cron --mapping <name>|--all
• hold-sync watch --mapping <name>|--all [--dry-run] [--interval-seconds <n>]

Watch Cadence

Require watch cadence to be configurable from user config:

• scheduling.watchIntervalSeconds controls watch poll frequency.
• mappings[].lookaheadDays controls rolling watch/reconcile window.

Recommend baseline values:

• watchIntervalSeconds: 900 (15 minutes)
• lookaheadDays: 1 (24 hours)

Working Model

• Use polling-based watch mode (hold-sync watch) for fast updates.
• Expect update latency approximately equal to watchIntervalSeconds.
• Treat this as self-hosted/operator-run automation.

Known Limits

• Do not assume webhook/push subscriptions are present; current fast sync path is polling.
• Keep periodic scheduled reconcile as fallback even when watch mode is enabled.

Required Tests

• metadata encode/decode round-trip
• overlap detection correctness
• idempotent reconcile upsert/delete behavior

Attribution: gog setup flow adapted from: - https://clawhub.ai/steipete/gog - https://github.com/steipete/gogcli - https://gogcli.sh/

Provider Notes (claude)

Use this variant for Claude-style workflows.

• Keep a short plan before major edits.
• Favor explicit assumptions and safety checks.
• Use the same command surface and config schema.

這個 Skill 質量不錯，功能設計清晰實用。它能自動將一個日曆的事件同步到另一個日曆顯示為"忙"，幫你避免重複預訂。配置靈活、支援多個日曆對映，有模擬執行模式和變更次數限制等安全措施，不容易出錯。文件說明詳細，安裝說明對新手友好。主要不足是同步延遲取決於設定的檢查間隔（最短約15分鐘），沒有即時推送；還需要手動安裝一個叫 gog 的命令列工具才能使用。總體適合需要跨日曆同步的使用者，質量可靠但有一定上手門檻。